第五章 文档

Python中 文档格式的事实标准是reStructuredText 简称 reST，是一种轻量级的标记语言，易于计算机处理，也易于人类阅读。
Sphinx（https://sphinx-doc.org/）是处理这一格式最常用的工具
安装
pip install sphinx
如果用官方源安装不了就换源。

项目的文档应该包含以下内容：

1 用一两句话描述这个项目要解决的问题
2 项目所基于的分发许可，如果是开源软件的话，应该再每一个文件里面包含相应的信息。
3 一个展示项目如何工作的小例子。
4 安装指南。
5 指向社区支持，邮件列表，IRC，论坛等的链接
6指向BUG跟踪系统的链接
7指向源代码的链接，以便开发人员可以下载并立刻投入开发。
还应该有一个README.rst文件，解释这个项目是干什么的，这个README.rst会显示在git（https://www.github.com）里面或者Pypi(https://pypi.python.org)上面

第一步

输入 生成命令
sphinx-quickstart
确认生成命令
Separate source and build directories (y/n) [n]: y
输入项目名称

Project name: lianxi100
输入作者姓名
Author name(s): 七天七念
Project release （项目计划或者描述）
之后会返回
如果文件要用英语以外的语言书写，
您可以通过语言代码在这里选择一种语言。斯芬克斯会的
将生成的文本翻译成该语言。
有关支持的代码列表，请参见
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.，
默认的是en，也就是英语，试下用zh_CN，最后面我会附加上语言的相应选项表
到此，会在顶级目录下生成build，跟source文件，

第二步

source里面主要包含了2个文件conf.py，它包含了Sphim的配置信息，另一个index.rst文件作为文档的首页。
按书上格式我应该写 sphinx-build 多线程练习\source 多线程练习\build
（注意的是上面的命令有2个参数，第一个参数是源目录也就是source，第二个目录应该只是随便什么名次都可以的）
，但是失败了，思考了下我在顶级目录之后我打 sphinx-build source build，成功输出了HTML文档到build文件里面
使用办法，再conf.py文件里面 替换extensions = [‘’]为extensions = ["sphinx.ext.autodoc"
]，开启文档的自动化功能。

第三步 rest写法注意

需要注意的是rest写法是有专门的写法的，需要"""+上文字才能被探测到一半的函数的写法，文字倒是无所谓是什么文字

#coding=UTF-8

def my_function(a, b):
    """函数功能说明
     天知道

    """
    return a * b

类的写法

class Demo1():
    """类的功能说明"""

    def add(self,a,b):
        """两个数字相加，并返回结果"""
        return a+b

    def google_style(arg1, arg2):
        """函数功能.

        函数功能说明.

        Args:
            arg1 (int): arg1的参数说明
            arg2 (str): arg2的参数说明

        Returns:
            bool: 返回值说明

        """
        return True

    def numpy_style(arg1, arg2):
        """函数功能.

        函数功能说明.

        Parameters
        ----------
        arg1 : int
            arg1的参数说明
        arg2 : str
            arg2的参数说明

        Returns
        -------
        bool
            返回值说明

        """
        return True

类似这里的
Returns
-------
再后面里面都会被消失
接着需要再conf.py 里面找到，这行代码大概在13-20行之间

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

取消他们的注释状态，修改为当前conf.py对于目标模块所在目录的路径，之后运行
sphinx-apidoc -o source ./
对各文档进行rst文档转化，接着用下面的命令
sphinx-build source build
对文档进行html输出到build文件夹里面

在书上写的没头没尾的，感觉是少了sphinx-apidoc -o source ./ 这个命令没有生成rst文件，估计全按书本上写的试验，没几个能写得出来。

之后的doctest，连官网上都没有多少这方面的资料，
命令为 sphinx-build -b doctest source build
这里应该只是把默认生成html文件的代码修改为生成了doctest其他细节跟上面的一样。
同时需要再conf.py里面加上生成器'sphinx.ext.doctest'，
如extensions = ["sphinx.ext.autodoc",'sphinx.ext.doctest'
]
之后会在build文件里面生成一个output.txt里面会记录你使用了doctest标记的次数
详细的可以参考下https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

到此python高手之路第五章文档，基本算是学习完毕了，这章出现了很大程度上的问题。在sphinx基础写法上，书上缺少了命令sphinx-apidoc -o source ./。
而在doctest上，也缺少了提示要开启生成器sphinx.ext.doctest
我感觉这玩意如果使用 的话，最好还是参考最后面网页上的例子开启全部的生成器为妙。
比如extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax']
估计下高手之路的作者认为看这边书的都是已经通达了python底层代码原理了的吧，好蛋疼，动不动就翻看源码的。
学习完毕，明天继续

附加语言选项

ar – Arabic
bn – Bengali
ca – Catalan
cak – Kaqchikel
cs – Czech
cy – Welsh
da – Danish
de – German
el – Greek
en – English
eo – Esperanto
es – Spanish
et – Estonian
eu – Basque
fa – Iranian
fi – Finnish
fr – French
he – Hebrew
hi – Hindi
hr – Croatian
hu – Hungarian
id – Indonesian
it – Italian
ja – Japanese
ko – Korean
lt – Lithuanian
lv – Latvian
mk – Macedonian
nb_NO – Norwegian Bokmal
ne – Nepali
nl – Dutch
pl – Polish
pt – Portuguese
pt_BR – Brazilian Portuguese
pt_PT – European Portuguese
ro – Romanian
ru – Russian
si – Sinhala
sk – Slovak
sl – Slovenian
sr – Serbian
sv – Swedish
ta – Tamil
tr – Turkish
uk_UA – Ukrainian
ur – Urdu
vi – Vietnamese
zh_CN – Simplified Chinese
zh_TW – Traditional Chinese

附加sphinx-build用法

sphinx-build 脚本构建了一个Sphinx文档集。用法如下:

$ sphinx-build [options] sourcedir builddir [filenames]

在这里，sourcedir 是指 源目录，builddir 是指你想指定的生成文档的目录。大部分时候，是不需要指定 filenames。

sphinx-build 脚本有如下的选项:

-b buildername

最重要的选项: 它选择生成器。常见的生成器如下：

html

生成HTML页面。这是默认生成器。

dirhtml

生成HTML页面，但是每个文件单独一个目录。如果web服务器提供服务，能够生成漂亮的URLs(没有 .html 后缀)。

singlehtml

整个内容生成一个HTML页面。

htmlhelp, qthelp, devhelp, epub

生成HTML文件，包含了生成上述格式的文档集合的其他信息。

latex

生成可以被编译成PDF文件的LaTeX源文件通过使用 pdflatex。

man

生成UNIX操作系统的groff格式的手册。

texinfo

生成Texinfo文件，它能够通过 makeinfo 处理成 Info 文件。

text

生成纯文本文件。

gettext

生成gettext的风格的消息目录（.pot 后缀的文件）。

doctest

如果 doctest 激活，执行文件中所有的doctests。

linkcheck

检查所有的外部链接的完整性。

请参看 Available builders，里面列出了Sphinx自身附带的所有的生成器。用户可以添加自己的生成器扩展。

-a

如果给定，总是生成所有输出文件。默认是只生成新的和更改的源文件的输出文件。（这可能并不适用于所有的生成器。）

-E

不要使用已保存的 环境 （系统缓存所有交叉引用），会完全重新生成。默认是仅仅读取和解析自上次运行后新的或者已更新的源文件。

-t tag

定义标签 tag。这跟 only 指令（标识符）关系密切，如果设置标签就会只包含 only 指令（标识符）的内容。

New in version 0.6.

-d path

因为Sphinx在生成输出文件之前，必须读取和解析所有的源文件，被解析过的源文件会被缓存为”doctree pickles”。通常，这些缓存文件会被放入于生成目录中的名为 .doctrees 的文件夹里；使用该选项可以选择不同的缓存文件夹（所有生成器都可以共享doctrees文件夹）。

-c path

使用给定的配置文件目录，忽略源文件中的 conf.py 配置文件。值得注意的是配置文件中的其他文件以及路径可能会跟配置文件目录有关，所以也必须使用指定的路径。

New in version 0.3.

-C

不使用配置文件；使用 -D 选项后的配置值。

New in version 0.5.

-D setting=value

覆盖配置文件 conf.py 中一个配置值对。该值必须是一个字符串或者字典值。对于字典值，需要给吃键值对类似：-Dlatex_elements.docclass=scrartcl。对于布尔值，使用 0 或者 1。

Changed in version 0.6: The value can now be a dictionary value.

-A name=value

在HTML模版中，把 value 赋给 name 。

New in version 0.5.

-n

运行在严格模式。目前，这会对所有丢失的引用抛出警告。

-N

禁止带颜色的输出。（Windows下任何的带颜色的输出都是无效的。）

-q

不要在标准输出上输出任何东西，只给出标准错误的警告和错误。

-Q

不要在标准输出上输出任何东西，也包括警告。只有错误被写入标准错误。

-w file

输出除标准错误外的警告（和错误）到指定的文件。

-W

把警告转换成错误输出。这就说构建会在第一个警告的时候停止，sphinx-build 会以错误状态1退出。

-P

（仅调试时有用。）构建时候，如果出现未处理的遗产，运行python调试器，pdb。

在命令行中，你可以在源目录以及生成目录后给出一个或者多个文件名。Sphinx 将会尝试构建给出的这些文件的输出（以及它们的依赖。）

Makefile选项

由 sphinx-quickstart 生成的 Makefile 和 make.bat 文件是只使用了 sphinx-build 的 -b 和 -d 参数。 然而， 它们支持以下的变量（参数）来定制化：

PAPER

latex_paper_size 的值。

SPHINXBUILD

替代 sphinx-build 的命令。

BUILDDIR

指定生成的目录，而不是使用在 sphinx-quickstart 中选择的路径。

SPHINXOPTS

sphinx-build 的附加选项。

调用sphinx-apidoc

sphinx-apidoc 能够对一个python包生成完全的自动的API文档。调用它像这样:

$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

packagedir 是指生成文档的包所在的路径， outputdir 生成的文档所存放的路径。任何给定的 pathnames 是在生成过程中需要忽略的路径名（[pathnames]里的东西在生成文档中是忽略的。）

sphinx-apidoc 有如下些选项:

-o outputdir

给出生成的文档所在的路径。

-f, --force

通常，sphinx-apidoc不会重新生成任何文件。使用这个选项强制重新生成所有的文件。

-n, --dry-run

使用这个选项的话，不会有任何文件生成。（空运行，或者称为干运行。）

-s suffix

这个选项指定了输出的文件的文件名后缀。默认情况下，后缀是 rst。

-d maxdepth

如果存在内容表，设置内容表的最大深度。

-T, --no-toc

这可以防止生成的表的内容文件 modules.rst。但是当 --full 给出的时候，本选项就不起作用了。

-F, --full

此选项使得sphinx-apidoc创建一个完整的Sphinx项目，与 sphinx-quickstart 使用同样的机制。大部分的配置值是设置成默认的值，但是你可以通过如下选项修改一些重要的配置值。

-H project

设置项目名称，使得生成到输出的文件 (请见 project).

-A author

设置作者名，使得生成到输出的文件 (请见 copyright).

-V version

设置项目版本，使得生成到输出的文件 (请见 version).

-R release

设置项目发布，使得生成到输出的文件 (请见 release).

参考资料：

命令使用大全http://www.pythondoc.com/sphinx/invocation.html，
使用参考例子 https://blog.csdn.net/sinat_29957455/article/details/83657029
官网网站资料 https://www.sphinx-doc.org/en/master/usage/configuration.html