Sphinx配置Python程序的文档

目录

• 资料
• 建立项目
  • 注释格式
    • 功能说明
    • Args
    • Returns
    • Examples
    • Notes
• 使用Sphinx生成文档
  • 安装Sphinx
  • 生成文档
    • 创建项目
    • 修改 conf.py
    • 修改 index.html
    • 生成html
• 报错解决方法
• Sphinx的一些理解
  • 文档组成
  • 成品
• ReadTheDocs
  • 版本控制

资料

https://www.yuque.com/xdd1997/gbrnie/qtmcq1

Sphinx英文手册：https://www.sphinx-doc.org/en/master/

Sphinx中文手册：https://sphinx-doc-zh.readthedocs.io/en/latest/contents.html

配置与注释可参考：

https://github.com/xdd1997/calfem-python

https://numpy.org/devdocs/reference/generated/numpy.cumsum.html

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#paragraphs

https://pandas.pydata.org/docs/reference/api/pandas.Series.to_numpy.html#pandas.Series.to_numpy

建立项目

1. 注意文件层次，对后面有影响

注释格式

"""Ex01

    Args:
        a(float): 加数
        b(float): 
            加数，
            这个参数很长，写了两行，文档会当作一行处理，所有第一行后面加了逗号
        
    Returns:
        float:只能写一个返回值，两个的还不会
        
    Examples:
        >>>
        c = my_add(1,2)
        c = my_add(1,2.3)

    Note:
        * test_2:111 https://xdd1997.github.io/ 
        * code:``test_2`` ,italic:`test_2`
        * `test_2`
"""

功能说明

• 功能说明可以在三个引号后面，也可以在下一行
• 用一个空行表示换行

Args

• Args与功能说明与之间必须有一个空行
• 参数说明较长时，可以写多行

Returns

• Returns与Args可以没有空行
• Returns下一行或者后面可以写None

Examples

Examples:
    >>>
    c = my_add(1,2)
    print('Xdd')
Examples:
    >>> c = my_add(1,2)
    >>> print('Xdd')
      	Xdd

Notes

• 默认是出现在一行，如果想换行就添加空行，或者用*来形成列表

使用Sphinx生成文档

安装Sphinx

pip install sphinx -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install sphinx_rtd_theme -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install sphinx_book_theme -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install recommonmark -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install jieba -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install sphinx-autobuild -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install sphinx-copybutton -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install sphinx-toggleprompt -i https://pypi.tuna.tsinghua.edu.cn/simple

或者

pip install sphinx sphinx_rtd_theme sphinx_book_theme recommonmark jieba sphinx-autobuild sphinx-copybutton sphinx-toggleprompt

生成文档

创建项目

• 打开cmd，切换到上述doc的路径，cd /d D:\test_Sphinx\doc ，输入sphinx-quickstart``---

• Separate source and build directories (y/n) [n]: y

• 一直回车即可

修改 conf.py

# -- Project information -----------------------------------------------------
project = 'test_Sphinx'
copyright = '2022, xdd2026@qq.com'
author = 'xdd2026@qq.com'
release = '1.0'
language = 'zh_CN'

# -- General configuration ---------------------------------------------------
import os
import sys
sys.path.insert(0, os.path.abspath(r'..\..\src\demo'))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.autosummary',
    "sphinx.ext.mathjax",
    'recommonmark',
    'sphinx_copybutton',
    'sphinx_toggleprompt'
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# html_theme = "sphinx_book_theme"
html_theme = 'sphinx_rtd_theme'
toggleprompt_offset_right = 35

html_static_path = ['_static']

修改 index.html

• 在文件index.rst文件加入modules.rst 或者 modules

.. test_Sphinx documentation master file, created by
   sphinx-quickstart on Fri Nov  4 14:33:35 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Sphinx 配置与项目文档生成
==============================================

.. toctree::
   :maxdepth: 1
   :caption: insall and use:

   markdown/sphinx_install.md

.. toctree::
   :maxdepth: 2
   :caption: src reference:

   modules.rst

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

生成html

• 在cmd (doc目录中），依次输入下面代码，用来从py文件中提取内容、生成html文件

注意:-o 后面跟的是保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录。然后在后面的是你的项目(代码)路径

sphinx-apidoc -o source ../src/demo -f
make clean & make html

• 双击打开 \doc\build\html\index.html

报错解决方法

D:\Git\test_Sphinx\doc\source\file01.rst: WARNING: document isn't included in any toctree

解决方法：可能是sphinx-apidoc -o source ../src/demo -f路径错误，确保../src/demo下面是py文件，

WARNING: autodoc: failed to import module 'file01'; the following exception was raised:

• 确认index.rst 文件中含有 modules或 modules.rst
• 修改conf.py文件中的路径，不清楚相对路径时，可写绝对路径，相对路径时根目录是sources。Sphinx只会提取该路径下py文件的注释。

Sphinx的一些理解

文档组成

1. 文档包括两部分，代码文档与后期文档。代码文档来自py文件中的注释，后期文档可来自md文件、rst文件与ipynb文件等
2. sphinx-apidoc -o source ../src/demo -f命令将demo文件夹中的.py文件中的注释生成文档，存放在doc/source文件夹下
3. index.rst是网页入口文件，每次重新生成文档时，这个文件不会被改变。上图中index.rst文件里面有两部分，

• • 第一部分是加载doc/source/markdown/sphinx_install.md文件，如果有多个md要依次填写。maxdepth=1表示只显示文件中最高的一级标题
  • 第二部分是加载doc/source/modules.rst文件，这是代码生成的文档入口，保留两个层级

1. 关于路径

• • conf.py 文件中的路径的根目录是source，也就是conf.py的路径，可使用绝对路径
  • index.rst文件中的路径的根目录是source，也就是index.rst的路径，添加其他markdown文件时只能在source或其子目录下
  • sphinx-apidoc 的根目录是 doc

成品

ReadTheDocs

https://github.com/xdd1997/test_Sphinx

https://test-sphinx-github.readthedocs.io/en/latest/

版本控制

需要github有分支

https://docs.readthedocs.io/en/stable/tutorial/