文檔生成工具：
自帶的pydoc，比較差
建議使用sphinx
安裝：
pip install sphinx
安裝主題：
由各種主題，我選擇常用的sphinx_rtd_theme
pip install sphinx_rtd_theme
使用方法：
1、創建文件夾doc：mkdir doc；cd doc；執行sphinx-quickstart，進入引導，根據需要選擇yes或者no
2、執行sphinx-quickstart引導程序只會生成一個index.rst
3、在doc目錄下執行sphinx-apidoc -o source file_directory，其中file_directory是指你需要文檔化的目錄，這樣如果有多個模塊，就會生成多個.rst文件
4、在doc目錄下執行make html，就會生成html文檔，打開html文檔，就可以了
sphinx文檔介紹
django項目的目錄結構，doc是用來文檔化的目錄，里面包含自動生成的目錄build、source、source/_static、source/_templates，文件config.py、make.bat、Makefile。其他目錄或者文件是make html報錯時，為解決問題添加的或者是make html生成的文件。
其中config.py是配置文件。source目錄下的.rst文件是源文件，index.rst負責首頁的布局。build目錄為生成的目標html文件，找到index.html打開就行
如何將Sphinx生成的html文檔集成進入Django：
https://www.cnblogs.com/flowjacky/p/6251177.html
使用sphinx-quickstart只會生成index.dst,需喲啊使用api
make html會提示錯誤，根據提示進行修改
-------------------------------------------------------------
以下內容來自：http://www.huangwenchao.com.cn/2015/12/djangp-sphinx.html
安裝 Sphinx 並且生成文檔項目
首先我們假設已經有了一個 django 項目的架構：
myproject/ myproject/ __init__.py settings.py urls.py wsgi.py myapp/ migrations/ __init__.py admin.py models.py tests.py views.py
在這個基礎上，我們要在里面加一個 docs 文件夾放文檔項目：
pip3 install Sphinx mkdir docs cd docs sphinx-quickstart # 注意 autodoc 的地方一定要選是，其他選默認沒什么問題。 # ... # 最后直接生成一下： make html
如上，先安裝 Sphinx 庫，然后創建一個目錄，在里面執行 sphinx-quickstart，填寫參數之后就可以產生文檔項目的內容。
這個時候，我們應該獲得一個這樣的目錄：
myproject/ myproject/ myapp/ docs/ _build/ doctrees/ html/ _static/ _templates/ conf.py index.rst Makefile
很好，我們現在通過 myproject/docs/_build/html/ 就已經獲得一個生成好的文檔靜態網站了，將這個目錄靜態部署，就已經搭好基本的文檔項目了。
撰寫基本的手工文檔
具體的 reStructuredText 語法，在這里就不多說了，本人其實將這篇文檔翻譯了一遍，不過還是自行參考原文吧：
然后，我們只需要在項目文檔里面創建文件結構以及 *.rst 文檔源文件，進行編輯即可。
比較關鍵的就是在文檔中搭建目錄引用關系，最終這些目錄樹會將所有文檔的章節拼接成一個整體的目錄樹：
例如我們在 docs/index.rst 里面加入這個目錄樹定義：
.. toctree:: :maxdepth: 3 usecases/index myapp/models myapp/admin myapp/views
這樣的話，對應會目錄到下面路徑的這幾個文件：
myproject/ docs/ usecases/ index.rst myapp/ admin.rst models.rst views.rst
注意，在我們計划中，usecases 用來存放純手寫的用例文檔，而 myapp 文件夾里面的內容是要打算在代碼中直接抽取的。
如何實現這一點？自動抽取代碼呢？
綁定 Django 項目並從項目生成代碼
首先，我們需要讓文檔項目的上下文能正確加載 django，就好像我們調用 python manage.py shell 得到的上下文一樣。
然后，我們在文檔里面就可以通過這樣的 reST 指令塊來指定抽取，以 myapp.model.rst 為例：
myapp.models module =================== .. automodule:: myapp.models :members: :undoc-members: :show-inheritance:
只要指定了這個 ..automodule 指令，再 make 就可以實現抽取。
但是，我們前面的這個前提“需要讓文檔項目的上下文能正確加載 django”這一點，並不是那么容易達到的，我就碰到了這個問題：
最終發現了需要在外部裝載 django 上下文的方法，參見：
也就是說，在這里的解決辦法是：
編輯 myproject/docs/conf.py，找到：
# sys.path.insert(0, os.path.abspath('.'))
附近這段，然后編輯成這幾行：
import django # 這個最好可以加載頂部和其他的 import 放在一起 # 這個注意由於 django 根目錄位於 `docs/conf.py` 本身的上一級目錄，因此要用父目錄 sys.path.insert(0, os.path.abspath('..')) # 下面將 settings 加到環境變量里面，等一下啟動的時候就會是用這個配置 os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings' # 關鍵，用這句加載模塊和上下文 django.setup()
有了這一套，就不會出現 django.core.exceptions.AppRegistryNotReady 的異常了。
-------------------------------------------------------------
sphinx-quickstart 引導過程：
➜ html sphinx-quickstart Welcome to the Sphinx 1.8.4 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: test > Author name(s): tester > Project release []: 1.0 If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]: zh_cn The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Indicate which of the following Sphinx extensions should be enabled: > autodoc: automatically insert docstrings from modules (y/n) [n]: y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: > coverage: checks for documentation coverage (y/n) [n]: > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: y > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]: Creating file ./source/conf.py. Creating file ./source/index.rst. Creating file ./Makefile. Creating file ./make.bat. Finished: An initial directory structure has been created. You should now populate your master file ./source/index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
django結合sphinx的config.py：
# -*- coding: utf-8 -*- # # Configuration file for the Sphinx documentation builder. # # This file does only contain a selection of the most common options. For a # full list see the documentation: # http://www.sphinx-doc.org/en/master/config # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # import sphinx_rtd_theme import django import os import sys sys.path.insert(0, os.path.abspath('./../../../erebus_app')) os.environ['DJANGO_SETTINGS_MODULE'] = 'erebus.settings' django.setup() # -- Project information ----------------------------------------------------- project = 'erebus_doc' copyright = '2019, deluopu' author = 'deluopu' # The short X.Y version version = '' # The full version, including alpha/beta/rc tags release = '1.0' # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones.
# 根據引導程序的選擇的擴展 extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The master toctree document. master_doc = 'index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # 選擇模板主題 # html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # # html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # The default sidebars (for documents that don't match any pattern) are # defined by theme itself. Builtin themes are using these templates by # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # # html_sidebars = {} # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'erebus_docdoc' # -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'erebus_doc.tex', 'erebus\\_doc Documentation', 'deluopu', 'manual'), ] # -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'erebus_doc', 'erebus_doc Documentation', [author], 1) ] # -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'erebus_doc', 'erebus_doc Documentation', author, 'erebus_doc', 'One line description of project.', 'Miscellaneous'), ] # -- Options for Epub output ------------------------------------------------- # Bibliographic Dublin Core info. epub_title = project # The unique identifier of the text. This can be a ISBN number # or the project homepage. # # epub_identifier = '' # A unique identification for the text. # # epub_uid = '' # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] # -- Extension configuration -------------------------------------------------
sphinx中文手冊： https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
英文手冊：http://www.sphinx-doc.org/en/master/usage/quickstart.html#defining-document-structure
pycharm的sphinx設置：
參考：
1、http://www.huangwenchao.com.cn/2015/12/djangp-sphinx.html
2、https://cloud.tencent.com/developer/ask/83415
3、https://www.cnblogs.com/ToDoToTry/p/9361838.html
4、https://www.cnblogs.com/niejinmei/p/8918858.html
5、https://www.jianshu.com/p/d4a1347f467b