sphinx 编写文档使用记录

目录

1、安装 sphinx 环境

首先安装 python 环境

这里可以安装 anacond ,使用起来比较方便。参考:Anaconda的安装和详细介绍(带图文)

我这里直接使用 scoop 来安装。

# 安装 miniconda 
scoop install -g miniconda3

Installing 'miniconda3' (4.7.12.1) [64bit]
Miniconda3-4.7.12.1-Windows-x86_64.exe (51.5 MB) [============================================================] 100%
Checking hash of Miniconda3-4.7.12.1-Windows-x86_64.exe ... ok.
Running installer... done.
Linking C:\scoop\apps\miniconda3\current => C:\scoop\apps\miniconda3\4.7.12.1
Creating shim for 'python'.
Creating shim for 'pythonw'.
Creating shim for 'python3'.
Persisting envs
'miniconda3' (4.7.12.1) was installed successfully!

然后安装 Sphinx 软件

打开 anaconda3 自带的 Anaconda Prompt ,输入下面命令进行安装

# 安装 Sphinx 本身,这里也可以使用 pip 安装
conda install Sphinx
# 安装 sphinxcontrib-fulltoc 插件
#  Sphinx 默认是不产生侧边栏的Tree 结构的,所以需要插件sphinxcontrib-fulltoc 
pip install sphinxcontrib-fulltoc

2、生成 Sphinx 工程

创建一个项目目录,然后进入目录,执行 sphinx-quickstart 命令。

这里会依次询问选项:

  • 分离源码和编译目录(y/n)
  • 工程名称:可以写中文
  • 作者名称:可以写中文
  • 工程发行版:写一个版本号就是。 Sphinx有一个“版本”和“发行版”的概念。每个版本可以有多个发行版本。例如,对于Python,版本类似于2.5或3.0,而发行版类似于2.5.1或3.0a1。如果不需要这种双重结构,只需将两者设置为相同的值。
  • 工程语言:zh_cn 是中文
sphinx-quickstart
Welcome to the Sphinx 2.4.4 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

The project name will occur in several places in the built documentation.
> Project name: helpdoc
> Author name(s): solym
> Project release []: 1.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

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.

3、编写并构建文档

具体的编写方式,可以参考:Sphinx 使用手册reStructuredText入门

编写完成文档之后,可以使用 make 脚本来生成目标格式文件,例如要生成 html 就执行 make html 即可,生成的目标文件在 build 目录下。

make
Sphinx v2.4.4
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)
上一篇:sphinx(六)sphinx 配置文件sphinx.conf配置项全解析


下一篇:使用ADO.NET对SQL Server数据库进行訪问