快速入门
sphinx提供了工具sphinx-quickstart用于快速生成一个文档工程
sphinx-quickstart
新建空文件夹，该目录下，输入命令sphinx-quickstart启动一个工程，随后根据需求选择配置
$ sphinx-quickstart
Welcome to the Sphinx 2.2.1 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: . # 默认以当前目录作为根目录，默认将根目录作为源文件路径
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 # 输入`y`可以设置将源文件和输出文件放置在两个不同文件夹内
The project name will occur in several places in the built documentation.
> Project name: sphinx_github_readthedocs # 输入工程名
> Author name(s): zhujian # 输入作者名
> Project release []: 2.0.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.
> Project language [en]: zh_CN # 默认工程语言为英文，设置`zh_CN`为中文
Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.
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.
工程结构
$ tree
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
4 directories, 4 files
build(或_build)是输出文件路径Makefile/make.bat是构建文件source是源文件路径(在文件conf.py中包含了所有的配置选项)
构建
如果已经生成了Makefile文件，那么直接使用make命令就好了
make builder
builder指要构建的格式，比如html,latex等等
$ make html
Running Sphinx v2.2.1
loading translations [zh_CN]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindexdone
writing additional pages... searchdone
copying static files... ... done
copying extra files... done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.
The HTML pages are in build/html.
然后进入./build/html，打开index.html即可
也可以使用工具sphinx-build进行编译，操作如下：
sphinx-build -b html sourcedir builddir
sourcedir指定源文件路径，builddir指定输出文件路径，-b html指定输出格式