sphinx 编写文档使用记录

Posted oloroso

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了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:scoopappsminiconda3current => C:scoopappsminiconda34.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 .sourceconf.py.
Creating file .sourceindex.rst.
Creating file .Makefile.
Creating file .make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .sourceindex.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.

配置主题和插件

Sphinx 生成的项目文件结构中,配置文件 conf.py 本身也是一个 python 脚本,所以进行修改的时候要注意符合 python 语法。

  • 配置主题:

    打开当前工程目录下的 source/conf.py 文件,找到 html_theme = ‘alabaster‘ 这一行,将主题名称(alabaster)修改为你喜欢的即可(当前可选:classicsphinxdocscrollsagogotraditionalnaturehaikupyramidbizstyle)。

    具体有哪些主题可以选择,可以查看官网文档 Sphinx home|Documentation ? HTML theming support

  • 配置插件:

    打开当前工程目录下的 source/conf.py 文件,找到extensions = [],在数组内(中括号内)添加需要的插件即可。比如说前面安装的 ‘sphinxcontrib.fulltoc‘ 就可以添加到里面。

    更多插件相关资料,可以查看官网文档 Sphinx home|Documentation ? Extensions

    插件 简述
    sphinx.ext.autosectionlabel 允许使用标题的参考章节
    sphinx.ext.mathjax
    sphinx.ext.jsmath
    sphinx.ext.imgmath
    Sphinx对HTML输出的数学公式支持
    mathjax / jsmath:通过 java script 渲染
    imgmath:渲染为图片

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编写文档

使用Sphinx编写文档

在使用Sphinx文档时,我应该告诉VCS忽略哪些文件? [关闭]

Sphinx 文档模块属性

在 Python Sphinx 中,有没有办法隐藏 autodoc 设置代码?