第五章 文檔

Python中 文檔格式的事實(shí)標(biāo)準(zhǔn)是reStructuredText 簡(jiǎn)稱(chēng) reST，是一種輕量級(jí)的標(biāo)記語(yǔ)言，易于計(jì)算機(jī)處理，也易于人類(lèi)閱讀。
Sphinx（https://sphinx-doc.org/）是處理這一格式最常用的工具
安裝
pip install sphinx
如果用官方源安裝不了就換源。

項(xiàng)目的文檔應(yīng)該包含以下內(nèi)容：

1 用一兩句話描述這個(gè)項(xiàng)目要解決的問(wèn)題
2 項(xiàng)目所基于的分發(fā)許可，如果是開(kāi)源軟件的話，應(yīng)該再每一個(gè)文件里面包含相應(yīng)的信息。
3 一個(gè)展示項(xiàng)目如何工作的小例子。
4 安裝指南。
5 指向社區(qū)支持，郵件列表，IRC，論壇等的鏈接
6指向BUG跟蹤系統(tǒng)的鏈接
7指向源代碼的鏈接，以便開(kāi)發(fā)人員可以下載并立刻投入開(kāi)發(fā)。
還應(yīng)該有一個(gè)README.rst文件，解釋這個(gè)項(xiàng)目是干什么的，這個(gè)README.rst會(huì)顯示在git（https://www.github.com）里面或者Pypi(https://pypi.python.org)上面

第一步

輸入 生成命令
sphinx-quickstart
確認(rèn)生成命令
Separate source and build directories (y/n) [n]: y
輸入項(xiàng)目名稱(chēng)

Project name: lianxi100
輸入作者姓名
Author name(s): 七天七念
Project release （項(xiàng)目計(jì)劃或者描述）
之后會(huì)返回
如果文件要用英語(yǔ)以外的語(yǔ)言書(shū)寫(xiě)，
您可以通過(guò)語(yǔ)言代碼在這里選擇一種語(yǔ)言。斯芬克斯會(huì)的
將生成的文本翻譯成該語(yǔ)言。
有關(guān)支持的代碼列表，請(qǐng)參見(jiàn)
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.，
默認(rèn)的是en，也就是英語(yǔ)，試下用zh_CN，最后面我會(huì)附加上語(yǔ)言的相應(yīng)選項(xiàng)表
到此，會(huì)在頂級(jí)目錄下生成build，跟source文件，

第二步

source里面主要包含了2個(gè)文件conf.py，它包含了Sphim的配置信息，另一個(gè)index.rst文件作為文檔的首頁(yè)。
按書(shū)上格式我應(yīng)該寫(xiě) sphinx-build 多線程練習(xí)\source 多線程練習(xí)\build
（注意的是上面的命令有2個(gè)參數(shù)，第一個(gè)參數(shù)是源目錄也就是source，第二個(gè)目錄應(yīng)該只是隨便什么名次都可以的）
，但是失敗了，思考了下我在頂級(jí)目錄之后我打 sphinx-build source build，成功輸出了HTML文檔到build文件里面
使用辦法，再conf.py文件里面 替換extensions = [‘’]為extensions = ["sphinx.ext.autodoc"
]，開(kāi)啟文檔的自動(dòng)化功能。

第三步 rest寫(xiě)法注意

需要注意的是rest寫(xiě)法是有專(zhuān)門(mén)的寫(xiě)法的，需要"""+上文字才能被探測(cè)到一半的函數(shù)的寫(xiě)法，文字倒是無(wú)所謂是什么文字

#coding=UTF-8

def my_function(a, b):
    """函數(shù)功能說(shuō)明
     天知道

    """
    return a * b

類(lèi)的寫(xiě)法

class Demo1():
    """類(lèi)的功能說(shuō)明"""

    def add(self,a,b):
        """兩個(gè)數(shù)字相加，并返回結(jié)果"""
        return a+b

    def google_style(arg1, arg2):
        """函數(shù)功能.

        函數(shù)功能說(shuō)明.

        Args:
            arg1 (int): arg1的參數(shù)說(shuō)明
            arg2 (str): arg2的參數(shù)說(shuō)明

        Returns:
            bool: 返回值說(shuō)明

        """
        return True

    def numpy_style(arg1, arg2):
        """函數(shù)功能.

        函數(shù)功能說(shuō)明.

        Parameters
        ----------
        arg1 : int
            arg1的參數(shù)說(shuō)明
        arg2 : str
            arg2的參數(shù)說(shuō)明

        Returns
        -------
        bool
            返回值說(shuō)明

        """
        return True

類(lèi)似這里的
Returns
-------
再后面里面都會(huì)被消失
接著需要再conf.py 里面找到，這行代碼大概在13-20行之間

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

取消他們的注釋狀態(tài)，修改為當(dāng)前conf.py對(duì)于目標(biāo)模塊所在目錄的路徑，之后運(yùn)行
sphinx-apidoc -o source ./
對(duì)各文檔進(jìn)行rst文檔轉(zhuǎn)化，接著用下面的命令
sphinx-build source build
對(duì)文檔進(jìn)行html輸出到build文件夾里面

在書(shū)上寫(xiě)的沒(méi)頭沒(méi)尾的，感覺(jué)是少了sphinx-apidoc -o source ./ 這個(gè)命令沒(méi)有生成rst文件，估計(jì)全按書(shū)本上寫(xiě)的試驗(yàn)，沒(méi)幾個(gè)能寫(xiě)得出來(lái)。

之后的doctest，連官網(wǎng)上都沒(méi)有多少這方面的資料，
命令為 sphinx-build -b doctest source build
這里應(yīng)該只是把默認(rèn)生成html文件的代碼修改為生成了doctest其他細(xì)節(jié)跟上面的一樣。
同時(shí)需要再conf.py里面加上生成器'sphinx.ext.doctest'，
如extensions = ["sphinx.ext.autodoc",'sphinx.ext.doctest'
]
之后會(huì)在build文件里面生成一個(gè)output.txt里面會(huì)記錄你使用了doctest標(biāo)記的次數(shù)
詳細(xì)的可以參考下https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

到此python高手之路第五章文檔，基本算是學(xué)習(xí)完畢了，這章出現(xiàn)了很大程度上的問(wèn)題。在sphinx基礎(chǔ)寫(xiě)法上，書(shū)上缺少了命令sphinx-apidoc -o source ./。
而在doctest上，也缺少了提示要開(kāi)啟生成器sphinx.ext.doctest
我感覺(jué)這玩意如果使用 的話，最好還是參考最后面網(wǎng)頁(yè)上的例子開(kāi)啟全部的生成器為妙。
比如extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax']
估計(jì)下高手之路的作者認(rèn)為看這邊書(shū)的都是已經(jīng)通達(dá)了python底層代碼原理了的吧，好蛋疼，動(dòng)不動(dòng)就翻看源碼的。
學(xué)習(xí)完畢，明天繼續(xù)

附加語(yǔ)言選項(xiàng)

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 腳本構(gòu)建了一個(gè)Sphinx文檔集。用法如下:

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

在這里，sourcedir 是指 源目錄，builddir 是指你想指定的生成文檔的目錄。大部分時(shí)候，是不需要指定 filenames。

sphinx-build 腳本有如下的選項(xiàng):

-b buildername

最重要的選項(xiàng): 它選擇生成器。常見(jiàn)的生成器如下：

html

生成HTML頁(yè)面。這是默認(rèn)生成器。

dirhtml

生成HTML頁(yè)面，但是每個(gè)文件單獨(dú)一個(gè)目錄。如果web服務(wù)器提供服務(wù)，能夠生成漂亮的URLs(沒(méi)有 .html 后綴)。

singlehtml

整個(gè)內(nèi)容生成一個(gè)HTML頁(yè)面。

htmlhelp, qthelp, devhelp, epub

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

latex

生成可以被編譯成PDF文件的LaTeX源文件通過(guò)使用 pdflatex。

man

生成UNIX操作系統(tǒng)的groff格式的手冊(cè)。

texinfo

生成Texinfo文件，它能夠通過(guò) makeinfo 處理成 Info 文件。

text

生成純文本文件。

gettext

生成gettext的風(fēng)格的消息目錄（.pot 后綴的文件）。

doctest

如果 doctest 激活，執(zhí)行文件中所有的doctests。

linkcheck

檢查所有的外部鏈接的完整性。

請(qǐng)參看 Available builders，里面列出了Sphinx自身附帶的所有的生成器。用戶(hù)可以添加自己的生成器擴(kuò)展。

-a

如果給定，總是生成所有輸出文件。默認(rèn)是只生成新的和更改的源文件的輸出文件。（這可能并不適用于所有的生成器。）

-E

不要使用已保存的 環(huán)境 （系統(tǒng)緩存所有交叉引用），會(huì)完全重新生成。默認(rèn)是僅僅讀取和解析自上次運(yùn)行后新的或者已更新的源文件。

-t tag

定義標(biāo)簽 tag。這跟 only 指令（標(biāo)識(shí)符）關(guān)系密切，如果設(shè)置標(biāo)簽就會(huì)只包含 only 指令（標(biāo)識(shí)符）的內(nèi)容。

New in version 0.6.

-d path

因?yàn)镾phinx在生成輸出文件之前，必須讀取和解析所有的源文件，被解析過(guò)的源文件會(huì)被緩存為”doctree pickles”。通常，這些緩存文件會(huì)被放入于生成目錄中的名為 .doctrees 的文件夾里；使用該選項(xiàng)可以選擇不同的緩存文件夾（所有生成器都可以共享doctrees文件夾）。

-c path

使用給定的配置文件目錄，忽略源文件中的 conf.py 配置文件。值得注意的是配置文件中的其他文件以及路徑可能會(huì)跟配置文件目錄有關(guān)，所以也必須使用指定的路徑。

New in version 0.3.

-C

不使用配置文件；使用 -D 選項(xiàng)后的配置值。

New in version 0.5.

-D setting=value

覆蓋配置文件 conf.py 中一個(gè)配置值對(duì)。該值必須是一個(gè)字符串或者字典值。對(duì)于字典值，需要給吃鍵值對(duì)類(lèi)似：-Dlatex_elements.docclass=scrartcl。對(duì)于布爾值，使用 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

運(yùn)行在嚴(yán)格模式。目前，這會(huì)對(duì)所有丟失的引用拋出警告。

-N

禁止帶顏色的輸出。（Windows下任何的帶顏色的輸出都是無(wú)效的。）

-q

不要在標(biāo)準(zhǔn)輸出上輸出任何東西，只給出標(biāo)準(zhǔn)錯(cuò)誤的警告和錯(cuò)誤。

-Q

不要在標(biāo)準(zhǔn)輸出上輸出任何東西，也包括警告。只有錯(cuò)誤被寫(xiě)入標(biāo)準(zhǔn)錯(cuò)誤。

-w file

輸出除標(biāo)準(zhǔn)錯(cuò)誤外的警告（和錯(cuò)誤）到指定的文件。

-W

把警告轉(zhuǎn)換成錯(cuò)誤輸出。這就說(shuō)構(gòu)建會(huì)在第一個(gè)警告的時(shí)候停止，sphinx-build 會(huì)以錯(cuò)誤狀態(tài)1退出。

-P

（僅調(diào)試時(shí)有用。）構(gòu)建時(shí)候，如果出現(xiàn)未處理的遺產(chǎn)，運(yùn)行python調(diào)試器，pdb。

在命令行中，你可以在源目錄以及生成目錄后給出一個(gè)或者多個(gè)文件名。Sphinx 將會(huì)嘗試構(gòu)建給出的這些文件的輸出（以及它們的依賴(lài)。）

Makefile選項(xiàng)

由 sphinx-quickstart 生成的 Makefile 和 make.bat 文件是只使用了 sphinx-build 的 -b 和 -d 參數(shù)。 然而， 它們支持以下的變量（參數(shù)）來(lái)定制化：

PAPER

latex_paper_size 的值。

SPHINXBUILD

替代 sphinx-build 的命令。

BUILDDIR

指定生成的目錄，而不是使用在 sphinx-quickstart 中選擇的路徑。

SPHINXOPTS

sphinx-build 的附加選項(xiàng)。

調(diào)用sphinx-apidoc

sphinx-apidoc 能夠?qū)σ粋€(gè)python包生成完全的自動(dòng)的API文檔。調(diào)用它像這樣:

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

packagedir 是指生成文檔的包所在的路徑， outputdir 生成的文檔所存放的路徑。任何給定的 pathnames 是在生成過(guò)程中需要忽略的路徑名（[pathnames]里的東西在生成文檔中是忽略的。）

sphinx-apidoc 有如下些選項(xiàng):

-o outputdir

給出生成的文檔所在的路徑。

-f, --force

通常，sphinx-apidoc不會(huì)重新生成任何文件。使用這個(gè)選項(xiàng)強(qiáng)制重新生成所有的文件。

-n, --dry-run

使用這個(gè)選項(xiàng)的話，不會(huì)有任何文件生成。（空運(yùn)行，或者稱(chēng)為干運(yùn)行。）

-s suffix

這個(gè)選項(xiàng)指定了輸出的文件的文件名后綴。默認(rèn)情況下，后綴是 rst。

-d maxdepth

如果存在內(nèi)容表，設(shè)置內(nèi)容表的最大深度。

-T, --no-toc

這可以防止生成的表的內(nèi)容文件 modules.rst。但是當(dāng) --full 給出的時(shí)候，本選項(xiàng)就不起作用了。

-F, --full

此選項(xiàng)使得sphinx-apidoc創(chuàng)建一個(gè)完整的Sphinx項(xiàng)目，與 sphinx-quickstart 使用同樣的機(jī)制。大部分的配置值是設(shè)置成默認(rèn)的值，但是你可以通過(guò)如下選項(xiàng)修改一些重要的配置值。

-H project

設(shè)置項(xiàng)目名稱(chēng)，使得生成到輸出的文件 (請(qǐng)見(jiàn) project).

-A author

設(shè)置作者名，使得生成到輸出的文件 (請(qǐng)見(jiàn) copyright).

-V version

設(shè)置項(xiàng)目版本，使得生成到輸出的文件 (請(qǐng)見(jiàn) version).

-R release

設(shè)置項(xiàng)目發(fā)布，使得生成到輸出的文件 (請(qǐng)見(jiàn) release).

參考資料：

命令使用大全http://www.pythondoc.com/sphinx/invocation.html，
使用參考例子 https://blog.csdn.net/sinat_29957455/article/details/83657029
官網(wǎng)網(wǎng)站資料 https://www.sphinx-doc.org/en/master/usage/configuration.html