Sphinx automated document

table of Contents

Sphinx

Sphinx is a tool that makes the creation of an intelligent and beautiful documentation easier. The author is Georg Brandl, based on BSD license. At first write Python documentation and the birth of Sphinx, now supports the generation of software development documentation for a variety of languages. Sphinx reStructuredText use as a written language, you can use Markdown + library expansion mode are written in the document.

Official website: https: //www.sphinx.org.cn/

It has the following outstanding features:

• Output formats : HTML (including Windows HTML Help files), LaTex (can be printed as a PDF), epub (the popular e-book format), Texinfo, manual pages (man manual), plain Text (plain text).
• CROSS REFERENCE wide : semantic tags and function, class, references, glossary terms and similar automatic link information.
• Layered architecture : easy to define document tree, automatically linked to the same level, superiors and subordinates.
• Auto Index : General Index as well as language-specific module index.
• Code highlighting : Highlighter using Pygments automatically highlighted.
• Extended : Automatic test code fragment, comprising Python modules (API documentation) documentation string like.
• Rich expansion : user contributed more than 50 extensions in the second repository, most of them can be installed from PyPI.

getting Started

• Installation : Sphinx rely Python2.4 and above.

pip3 install -U sphinx

• Creating Documentation Project : created in the root directory of the project doc subdirectory and execute the document creation instruction, you need to enter some interaction during configuration.

$ sphinx-quickstart 

mickeyfan$ sphinx-quickstart
欢迎使用 Sphinx 2.4.3 快速配置工具。

请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。

已选择根路径：.

布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y

项目名称会出现在文档的许多地方。
> 项目名称: 5G Provider
> 作者名称: fanguiju
> 项目发行版本 []: v1.0

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.
> 项目语种 [en]: zh_CN

创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。

完成：已创建初始目录结构。

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。 用 Makefile 构建文档，像这样：
 make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

• Configuration : documents created after the project, you can see what files or subdirectories:

  • Makefile : using a makecommand, the instructions may be used (EG sphinx-build) to construct output document.
  • _build : This is the directory used to store the generated trigger a specific output file.
  • _static : not all belong to the source code (eg pictures) are part of a file stored in here, we would link them together later in the build directory.
  • conf.py : Sphinx is used to store configuration values, including the terminal performs sphinx-quickstartthose values when selected.
  • index.rst : root directory Documentation Project. If you divide a document into another file, the directory will connect these documents.

• Documenting : after the main title in index.rst file, there is a list of the contents, including the toctreestatement, it will bring together all the documents are linked to the Index. E.g:

# 我们想将一个新文件添加到文档中，并打算将其命名为 example.rst。

Contents:

.. toctree::
   :maxdepth: 2

   example

Note: the following content example.rst

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers! 

• Generate a document : Run makefate, and HTML specified as the output format. The output can be directly used as the site because it contains all generated content, including JavaScript and CSS files.

$ make html

docs run-test: commands[0] | sphinx-build -W -b html doc/source doc/build/html
正在运行 Sphinx v2.4.3
正在加载翻译 [zh_CN]... 完成
制作输出目录... 完成
构建 [mo]： 0 个 po 文件的目标文件已过期
构建 [html]： 1 个源文件的目标文件已过期
更新环境: [新配置] 已添加 1，0 已更改，0 已移除
阅读源... [100%] index

查找当前已过期的文件... 没有找到
pickling环境... 完成
检查一致性... 完成
准备文件... 完成
写入输出... [100%] index

generating indices...  genindex完成
writing additional pages...  search完成
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
构建 成功.

HTML 页面保存在 doc/build/html 目录。

• Generate static pages : As we finish the previous operation, after generating HTML from two files, we have a complete static page website. Using the browser to access the build / index.html file in the html directory

• Add images and other static files : as long as the static files are placed _static directory (Sphinx create the directory when you create a document layout), you can easily reference it. . example.rst static list is as follows:

.. image:: _static/system_activity.jpg

• Modify skin : sphinx provided by default a lot of optional skin, we can conf.py adjusted by modifying, for example:

html_theme = "classic"

• Use sphinx_rtd_theme skin :
  • installation

pip3 install sphinx_rtd_theme

- 配置

# conf.py

html_theme = 'sphinx_rtd_theme'

- 重新构建

make html

reStructuredText syntax

Headings, lists, text, points

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

form

.. csv-table::
    :header:参数,类型,含义
    :widths:2,2,5

    test1,String,这里是测试的第一行
    test2,int,这里是测试的第二行

Block

.. code-block:: xml

    public void test(){
        throws new Exception("this is a test");
    }

References to other module files

.. toctree::
    :macdepth: 3

    module one
    module two

Click Jump

调用 :ref:`点击这里跳转<file.key>`

Reference a static picture

.. image:: _static/system_activity.jpg