配置狮身人面像¶
本指南用于在Ubuntu上配置sphinx。
在项目的根目录中（如果需要，请替换<projectu name>），为文档（如果文档不存在）创建一个名为docs的文件夹：
cd
cd <PROJECT_NAME>
mkdir docs
cd docs
Sphinx快速启动¶
sphinx快速启动脚本为项目执行一次性设置。如果尚未为项目配置sphinx，请使用以下命令运行它：
sphinx-quickstart
接受根路径的默认值：
Enter the root path for documentation.
> Root path for the documentation [.]:
重写默认值，使其具有单独的源目录和生成目录：
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
接受名称前缀的默认值：
> Name prefix for templates and static dir [_]:
输入项目名称和名称：
The project name will occur in several places in the built documentation.
> Project name: <PROJECT_NAME>
> Author name(s): <AUTHOR_NAME>
输入项目的版本和版本号：
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: <X.Y>
> Project release [0.2]: <X.Y.Z>
选择语言（默认为英语）：
> Project language [en]:
您需要决定重构文本的文件后缀。已阅读docs建议使用.txt扩展名（请参见： http://documentation-style-guide-sphinx.readthedocs.io/ 不过，我个人更喜欢使用.rst扩展名，这样就可以清楚地知道文件的格式。您的选择：
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]:
接受EPUB的默认值：
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:
如果有python代码自动记录，请选择启用autodoc：
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
接受默认值，除了Windows（除非需要）：
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
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]:
> Create Windows command file? (y/n) [y]: n
输出：
Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Finished: An initial directory structure has been created.
You should now populate your master file ./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.
这样的目录结构将被创建：
+-- docs
¦ +-- build
¦ +-- Makefile
¦ +-- source
¦ +-- conf.py
¦ +-- index.rst
¦ +-- _static
¦ +-- _templates
狮身人面像的初始配置现在已经完成，继续阅读，因为还有更多的任务需要完成。