• Sphinx 自动化文档


    目录

    Sphinx

    Sphinx 是一个工具,它使得创建一个智能而美丽的文档变得简单。作者是 Georg Brandl,基于 BSD 许可证。起初为写 Python 文档而诞生的 Sphinx,现在已经支持为各种语言生成软件开发文档。Sphinx 使用 reStructuredText 作为编写语言,也可以使用 Markdown+拓展库 的方式进行文档的编写。

    官方网站:https://www.sphinx.org.cn/

    它具有以下突出特性:

    • 输出格式:HTML(包括 Windows 的 HTML 帮助文件)、LaTex(可以打印为 PDF)、epub(流行的电子书格式)、Texinfo、manual pages(man 手册)、plain Text(纯文本)。
    • 广泛的交叉引用:语义标记和函数,类,引用,词汇表术语和类似信息的自动链接。
    • 分层架构:轻松定义文档树,自动链接到平级,上级和下级。
    • 自动索引:一般索引以及特定于语言的模块索引。
    • 代码高亮:使用Pygments荧光笔自动突出显示。
    • 扩展:自动测试代码片段,包含 Python 模块(API 文档)中的文档字符串等。
    • 丰富的拓展:用户在第二个存储库中贡献了 50 多个扩展,其中大多数可以从 PyPI 安装。

    入门

    • 安装:Sphinx 依赖 Python2.4 及以上版本。
    pip3 install -U sphinx
    • 创建文档项目:在项目的根目录下创建 doc 子目录,并执行文档创建指令,期间你需要交互输入一些配置。
    $ 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。
    • 配置:创建好文档项目之后,可以看见一下文件或子目录:

      • Makefile:在使用 make 命令时,可以使用这些指令(e.g. sphinx-build)来构建文档输出。
      • _build:这是触发特定输出后用来存放所生成的文件的目录。
      • _static:所有不属于源代码(e.g. 图片)一部分的文件均存放于此处,稍后会在构建目录中将它们链接在一起。
      • conf.py:用于存放 Sphinx 的配置值,包括在终端执行 sphinx-quickstart时选中的那些值。
      • index.rst:文档项目的 root 目录。如果将文档划分为其他文件,该目录会连接这些文件。
    • 编写文档:在 index.rst 文件中的主标题之后,有一个内容清单,其中包括 toctree 声明,它将所有文档链接都汇集到 Index。例如:

    # 我们想将一个新文件添加到文档中,并打算将其命名为 example.rst。
    
    Contents:
    
    .. toctree::
       :maxdepth: 2
    
       example

    注: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!
    • 生成文档:运行 make 命运,并将 HTML 指定为输出格式。可直接将该输出用作网站,因为它包含了生成的所有内容,包括 JavaScript 和 CSS 文件。
    $ 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 目录。
    • 生成静态网页:随着我们完成前面的操作,从两个文件中生成 HTML 之后,我们就拥有一个完整的静态页面网站。使用浏览器访问 build/html 目录下的 index.html 文件

    在这里插入图片描述

    • 添加图片等静态文件:只要将静态文件放置 _static 目录(Sphinx 在创建文档布局时创建了该目录)中,就可以轻松地对其进行引用。。example.rst 的静态清单如下:
    .. image:: _static/system_activity.jpg
    • 修改皮肤:sphinx 默认提供了好多可选的皮肤,我们可以通过修改 conf.py 调整,比如:
    html_theme = "classic"
    • 使用 sphinx_rtd_theme 皮肤
      • 安装
    pip3 install sphinx_rtd_theme
    - 配置
    # conf.py
    
    html_theme = 'sphinx_rtd_theme'
    - 重新构建
    make html

    reStructuredText 语法格式

    标题、列表、正文、要点

    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!

    表格

    .. csv-table::
        :header:参数,类型,含义
        :widths:2,2,5
    
        test1,String,这里是测试的第一行
        test2,int,这里是测试的第二行

    代码块

    .. code-block:: xml
    
        public void test(){
            throws new Exception("this is a test");
        }

    引用其他模块文件

    .. toctree::
        :macdepth: 3
    
        module one
        module two

    点击跳转

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

    引用静态图片

    .. image:: _static/system_activity.jpg

    相关阅读:

  • 相关阅读:

    类(重要的很)
    异常
    异常
    面向对象oop接口
    面向对象oop多态
    Day10_数组(下)
    Day09_数组(上)
    Day08_网络编程(上)
    Day07_java对象下
  • 原文地址:https://www.cnblogs.com/hzcya1995/p/13309396.html
Copyright © 2020-2023  润新知