如何创建readthedoc

编程 > python python

发布时间 : 2022-12-19 10:05

阅读 :

在项目中创建
主题
autodoc
定义开始文件为 index
本地创建 html
发布

readthedocs官方教程文档
 sphinx中文文档
 reStructuredText 教程

在项目中创建

一般使用的是shpinx, 在项目根目录中创建docs文件夹

cd docs
sphinx-quickstart

推荐还是将 build 和 source 分开

主题

推荐使用sphinx_rtd_theme主题，首先需要安装

pip install sphinx-rtd-theme

然后在conf.py中使用

conf.py

import sphinx_rtd_theme


html_theme = 'sphinx_rtd_theme'

autodoc

中文文档

在docs/requirements.txt 文件中定义需要的python包

docs/requirements.txt

alabaster==0.7.12
Sphinx==5.3.0
sphinx-rtd-theme==1.1.1
sphinx-copybutton==0.5.0

在conf.py中引入，然后进行扩展定义

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('..'))


extensions = [
    'sphinx.ext.autodoc',
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx.ext.autosectionlabel",
    'sphinx_copybutton',
]

.. autoclass:: net_inspect.NetInspect
   :members: 
   :undoc-members:

如果构建不成功，去readthedocs 构建里面查看原因，有可能是因为有些模块没有引入，
这时候就需要在docs/requirements.txt中加入这个模块即可。

构建不成功参考问答

定义开始文件为 index

conf.py

master = 'index'

本地创建 html

./make.bat clean ; ./make.bat html

发布

readthedocs 中导入项目即可，成功后每次github上面有更新，readthedocs会自动更新

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 365433079@qq.com