文档生成
文档生成主要有 pydoc(python 官方自带的)，我看了下不是很好看。
感觉还是 Python-Sphinx 比较符合我的审美。
Sphinx
intro
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText sources)。
install
pip install Sphinx
测试代码
我创建了一个测试代码
- test.py
# -*-coding:utf-8-*-
def init_test():
'''
用于初始化项目测试，不需要任何参数
:return:
'''
print("初始化项目")
路径如下：
houbinbindeMacBook-Pro:test houbinbin$ ls
README.md test.py
houbinbindeMacBook-Pro:test houbinbin$ pwd
/Users/houbinbin/code/_python/openccpy/test
quick-start
基本全是默认，除了项目名称必须填写。
$ sphinx-quickstart
日志如下：
$ sphinx-quickstart
Welcome to the Sphinx 1.8.1 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: openccpy
> Author name(s): binbin.hou
> Project release []: 0.0.2
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]:
> 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]: y
> Create Windows command file? (y/n) [y]: 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.
- 生成文件目录
$ tree
.
├── Makefile
├── build
├── make.bat
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
设置 index.rst
默认生成 index.rst 如下：
.. toctree::
:maxdepth: 2
:caption: Contents:
调整如下：
.. toctree::
:maxdepth: 2
:caption: Contents:
../test
../test 为测试文件对应的位置
配置 conf.py
修改风格
conf.py
#html_theme = ‘default’
#html_theme = ‘alabaster’
html_theme = 'sphinxdoc'
配置
修改原始内容：
# -- 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 os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
为你的代码对应路径
import os
import sys
sys.path.insert(0, os.path.abspath('../test'))
生成rst文件
-o 后面跟的是保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录。
然后在后面的是你的项目(代码)路径
$ pwd
/Users/houbinbin/code/_python/openccpy/docs
$ sphinx-apidoc -o ./source ./../../test/
Creating file ./source/test.rst.
Creating file ./source/modules.rst.
最后执行make html,生成html文件
$ pwd
/Users/houbinbin/code/_python/openccpy/docs
$ make html
正在运行的是 Sphinx v1.8.1
创建输出目录…
...
导出对象清单……完成
build 成功, 2 warnings.
HTML 页面保存在 _build/html 目录。
报错
test.rst:4 WARNING: Unknown directive type "automodule".
- 问题
sphinx-error-unknown-directive-type-automodule-or-autoclass
- 修正
修改 conf.py
从
extensions=[]
到
extensions = ['sphinx.ext.autodoc']
报错
source/modules.rst: WARNING: document isn't included in any toctree
- 问题
warning-document-isnt-included-in-any-toctree-for-included-file
- 修复
浏览器查看
浏览器直接打开对应的 html，页面比较朴素
Welcome to openccpy’s documentation!
Indices and tables
Index
Module Index
Search Page
openccpy
Navigation
Quick search
©2019, binbin.hou. | Powered by Sphinx 1.8.1 & Alabaster 0.7.11 | Page source
其他样式
安装
pip install sphinx_rtd_theme
执行
conf.py
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
参考资料
- pydoc
- sphinx
