write_the_doc

Author

RYefccd

Date

2019-08-08T08:26:11.588674+08:00

文档环境及其依赖

pip install sphinx

quickstart

(sphinx) ubuntu@pytorch:~/sphinx$ sphinx-quickstart demo/
Welcome to the Sphinx 2.1.2 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: demo/

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

The project name will occur in several places in the built documentation.
> Project name: myproject
> Author name(s): fccd
> Project release []: 0.0.1

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
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:

Creating file demo/source/conf.py.
Creating file demo/source/index.rst.
Creating file demo/Makefile.
Creating file demo/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file demo/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.

(sphinx) ubuntu@pytorch:~/sphinx$ ls demo/
Makefile  build  make.bat  source

(sphinx) ubuntu@pytorch:~/sphinx/demo$ make html
Running Sphinx v2.1.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in build/html.

初始配置

conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains 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 os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'myproject'
copyright = '2019, fccd'
author = 'fccd'

# The full version, including alpha/beta/rc tags
release = '0.0.1'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# 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 = []


# -- 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'

# 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']

修改配置

read the doc 风格文档

依赖:

pip install sphinx-rtd-theme

修改配置:

# 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'

支持 markdown 格式

sphinx 默认支持 restructureText 格式, 如果需要支持 markdown 格式, 需要导入依赖和修改相关配置.

依赖:

pip install recommonmark

# markdown support
from recommonmark.parser import CommonMarkParser

source_parsers = {'.md': CommonMarkParser}
source_suffix = ['.rst', '.md']

支持 markdown table 格式

感谢胡达聪提供协助

sphinx 默认支持 restructureText 格式, 如果需要支持 markdown 格式, 需要导入依赖和修改相关配置. 目前 recommonmark 不支持 markdown table 的渲染, 如果需要支持, 请把 sphinx_markdown_tables 添加到 conf.py 配置文件中.

依赖:

pip instal sphinx-markdown-tables

extensions = [
 'sphinx_markdown_tables',
 ]

支持ipynb(notebook)文件格式

感谢胡达聪提供协助

依赖:

pip install nbsphinx

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'nbsphinx',
'sphinx.ext.mathjax',
]

支持中文搜索

感谢黄奇鹏提供配置

依赖:

pip install jieba

# 支持中文搜索
html_search_language = 'zh'

构建中文pdf

https://docs.readthedocs.io/en/stable/guides/pdf-non-ascii-languages.html

For docs that are not written in Chinese or Japanese, and if your build fails from a Unicode error, then try xelatex as the latex_engine instead of the default pdflatex in your conf.py:

latex_engine = 'xelatex'

When Read the Docs detects that your documentation is in Chinese or Japanese, it automatically adds some defaults for you.

For Chinese projects, it appends to your conf.py these settings:

latex_engine = 'xelatex'
latex_use_xindy = False
latex_elements = {
    'preamble': '\\usepackage[UTF8]{ctex}\n',
}

autobuild

感谢曹佳豪提供此技巧分享

在撰写文档时, 每次想要看到效果都要执行 make html 才能看到渲染的 html 文档. 为了能够 提升编辑文档的效率, 建议使用 autobuild 扩展. 一旦我们修改相关的文档和 conf.py 配置时, 就会自动触发构建.

依赖:

pip install sphinx-autobuild

使用:

sphinx-autobuild source build/html -H 0.0.0.0 -p 8000
最后在 http://localhost:8000 访问即可.

或者把这个放在 Makefile 中:

Makefile

livehtml:
	mkdir -p $(BUILDDIR)/html/

make livehtml

日常撰写文档流程

1. 开启自动文档构建

   sphinx-autobuild source build/html -p 8000 -H 0.0.0.0
   # 或者
   make livehtml  # 参见上面的 Makefile 配置
   

2. 撰写文档

   (sphinx) ubuntu@pytorch:~/sphinx/demo$ touch source/restructText_demo.rst
   (sphinx) ubuntu@pytorch:~/sphinx/demo$ touch source/markdown_StackEdit.md
    ...
   (sphinx) ubuntu@pytorch:~/sphinx/demo$ tree -l 2 .
   .
   ├── Makefile
   ├── make.bat
   └── source
       ├── _static
       ├── _templates
       ├── birthday-paradox.png
       ├── conf.py
       ├── index.rst
       ├── markdown_StackEdit.md
       └── restructText_demo.rst
   

3. 保存(crtl+s)触发自动构建

4. 在 http://localhost:8000/ 查看文档即可.

文档展示

rst 语法参考: https://3vshej.cn/rstSyntax/index.html

个人笔记: https://write-docs.readthedocs.io/en/latest/index.html

python-cookbook: https://python-cookbook-3rd-edition.readthedocs.io/zh_CN/latest/