文档生成

文档生成主要有 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

python3 pydoc

Python编程：使用pydoc生成文档注释

  • sphinx

快速开始

自动生成Python项目文档

Sphinx-doc编写文档