首页 > 编程语言 >Sphinx配置Python程序的文档

Sphinx配置Python程序的文档

时间:2022-11-12 13:46:11浏览次数:57  
标签:Sphinx Python html 文档 https rst sphinx

目录

资料

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. 注意文件层次,对后面有影响

img

注释格式

"""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`
"""

功能说明

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

img

Args

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

img

Returns

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

Examples

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

img

Notes

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

img

使用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, [email protected]'
author = '[email protected]'
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的一些理解

img

文档组成

  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

成品

img

ReadTheDocs

https://github.com/xdd1997/test_Sphinx

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

版本控制

需要github有分支

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

标签:Sphinx,Python,html,文档,https,rst,sphinx
From: https://www.cnblogs.com/xdd1997/p/16883578.html

相关文章

  • Python第一个程序
    Python第一个程序1.*使用文本编辑器在Python的交互式命令行写程序,好处是一下就能得到结果,坏处是没法保存,下次还想运行的时候,还得再敲一遍。所以,实际开发的时候,我们总是......
  • 使用python保存网页时print能显示正常,html打开中文乱码问题
             ......
  • python之文件读写
    ###这段代码是用于读文件、写文件###fromsysimportargvfromos.pathimportexistsscript,from_file,to_file=argv#获取文件内容in_file=open(from_file......
  • python的字典
    语法字典是通过{}来表示的,每一条数据都是一个键值对(key:value),每个元素之间使用逗号隔开字典中的键:只能是不可变类型的数据,一般情况下都是使用字符串来作为字典的键注......
  • Python String Slicing
    StringsandCharacterDatainPython StringSlicingPythonalsoallowsaformofindexingsyntaxthatextractssubstringsfromastring,knownasstringsl......
  • python 某猫投诉加密解析
    importhashlibimportjsonimportrandomimporttimeimportrequestssha256=hashlib.sha256()'''某猫投诉https://jiangsu.tousu.sina.com.cn/'''classBlackCatComplain......
  • 元进Python(4)---networkx制作我最喜爱55部美剧天体排名
    利用networkx和matplotlib给我最喜爱的55部美剧来个天体排名【最终呈现效果】【代码实现及注释】importnetworkxasnximportmatplotlib.pyplotaspltUSTVNode=['Everybo......
  • python10
    一、创建并打开记录蚂蚁庄园动态的文件print("\n","="*10,"蚂蚁庄园动态","="*10)film=open('message.txt','w')print("\n即将显示……\n")  二、向蚂蚁庄园的动态文......
  • python apscheculer 报错 skipped: maximum number of running instances reached (1
    apscheduler定时任务报错skipped:maximumnumberofrunninginstancesreached(1)原因是默认max_instances最大定时任务是1个,可以通过在add_job中调max_instances增加......
  • Python实验报告——第10章 文件及目录操作
    实验报告实例01:创建并打开记录蚂蚁庄园动态的文件代码如下:print('\n','='*10,'蚂蚁庄园动态','='*10)file=open('message.txt','w')print('\n即将显示……\n')......