安装

前提，安装了 python 和 python-pip

  • windows
    在 cmd 窗口中执行 pip install Sphinx
  • ubuntu
    1
    sudo pip install Sphinx

创建 Sphinx 项目

1
sphinx-quickstart

  • 设定文档的根目录：

    1
    2
    Enter the root path for documentation.
    > Root path for the documentation [.]:

    默认为 .，即当前目录，或者也可以新建目录 ./xxx。

  • 是否分离 “_build” 文件夹

    1
    2
    3
    4
    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

  • 设置 templates 和 static 文件夹的前缀，默认为``.

    1
    2
    3
    4
    Inside the root directory, two more directories will be created; "_templates"
    for custom HTML templates and "_static" for custom stylesheets and other static
    files. You can enter another prefix (such as ".") to replace the underscore.
    > Name prefix for templates and static dir [_]:

  • 设置项目的名称和作者

    1
    2
    3
    The project name will occur in several places in the built documentation.
    > Project name: wiki-zhongniu
    > Author name(s): lizs

  • 设置项目的版本号

    1
    2
    3
    4
    5
    6
    7
    Sphinx has the notion of a "version" and a "release" for the
    software. Each version can have multiple releases. For example, for
    Python the version is something like 2.5 or 3.0, while the release is
    something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
    just set both to the same value.
    > Project version: v1.0
    > Project release [v1.0]:   // 默认为上面输入的 veision

  • 设置项目的编写语言

    1
    2
    3
    4
    5
    6
    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
    http://sphinx-doc.org/config.html#confval-language.
    > Project language [en]: zh_CN

  • 设置源文件的后缀

    1
    2
    3
    The file name suffix for source files. Commonly, this is either ".txt"
    or ".rst".  Only files with this suffix are considered documents.
    > Source file suffix [.rst]:

  • 设置文档首页的名称

    1
    2
    3
    4
    5
    One document is special in that it is considered the top node of the
    "contents tree", that is, it is the root of the hierarchical structure
    of the documents. Normally, this is "index", but if your "index"
    document is a custom template, you can also set this to another filename.
    > Name of your master document (without suffix) [index]:

  • 设置是否 epub 输出，默认即可

    1
    2
    Sphinx can also add configuration for epub output:
    > Do you want to use the epub builder (y/n) [n]:

  • 设置是否使用 Sphinx 扩展功能：

    1
    2
    Please indicate if you want to use one of the following Sphinx extensions:
    > autodoc: automatically insert docstrings from modules (y/n) [n]: y

  • 然后，选择需要的 extension。

  • 创建 Makefile 和 Windows command file

    1
    2
    3
    A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly.
    > Create Makefile? (y/n) [y]: y
    > Create Windows command file? (y/n) [y]: y

  • 生成 HTML 文件
    执行完以上步骤之后，就会在当前文件夹下生成一个目录为 xxx 的项目文件。进入文件夹里面，可以看到生成了 Makefile 文件。这时候，就可以用 make 命令来生成 html 文件了

    1
    make html

    执行完 make html 会在 _build 文件夹里面的 html 文件夹里可以看到生成的 html 文件。如果分离了 _build，html 文件会在 build 的 html 文件夹里面。