GitHub-Flavored Markdown (GFM)이 python의 가장 흔한 Markup 언어다. (심지어 지금 요약도 GFM으로 작성되었다!)
GFM 스펙은 아래 링크에서 확인할 수 있다.
.md 파일을 이용해서 document를 작성한 뒤에는 MkDocs나 Sphinx를 이용해서 정적 사이트로 변환할 수 있다.
Django 프로젝트는 아래와 같은 문서들을 포함해야 한다.
README.md: 프로젝트에 대한 간단한 설명,docs/디렉토리 위치를 적는다.docs/: 프로젝트에 대한 문서들을 포함한다.docs/deployment.md: 프로젝트 배포 방법을 설명한다.docs/installation.md: 프로젝트 세팅을 위한 설치 방법을 설명한다.docs/architecture.md: 프로젝트의 아키텍처를 설명한다.
- python.org/dev/peps/pep-0257 docstring에 대한 스펙 문서
- readthedocs.io
MkDocs나Sphinx를 이용해서 생성한 정적 사이트를 무료로 호스팅해주는 서비스 - pythonhosted.org 또다른 무료 호스팅 서비스
- en.wikipedia.org/wiki/Markdown Markdown에 대한 위키 문서
ReStructuredText는 마크다운과 크게 다르지 않은 일반 텍스트 서식 지정 구문이다. 마크다운보다 훨씬 더 많은 기능이 내장되어 있지만 배우기가 더 어렵고 작성 속도가 느리다. Django, Python 및 많은 구형 써드파티 라이브러리와 같은 핵심 도구에서 사용된다.
Markdown과 ReStructuredText는 서로 호환되지 않는다. 따라서 Markdown으로 작성된 문서를 ReStructuredText로 변환하거나 그 반대로 변환해야 할 때가 있다. 이런 경우에는 pandoc을 사용하면 된다.
어떤 이유로든 프로젝트 자체에 문서를 배치할 수 없다면 다른 옵션이 있어야 한다. 위키, 온라인 문서 저장소, 블로그 등을 이용해줄 수 있다.
25.3에서 제안한 것과 같은 이름으로 내용을 표시하는 것이 좋다.
코드에 대한 문서는 docstring을 이용해서 작성한다. docstring은 함수, 클래스, 메서드, 모듈, 패키지에 대한 설명을 작성하는데 사용된다. docstring은 __doc__ 속성을 통해 접근할 수 있다.
이런 docstring을 interrogate 라이브러리를 이용해서 강제할 수 있다.