使用sphinx生成python项目文档

Posted 2022-11-10 _iorilan

#1

pip install sphinx

#2

sphinx-quickstart

#3

修改 conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
#确保module可以找到 .e.g.
#sys.path.insert(0, os.path.abspath('../../sample_module'))

html_theme = 'classic'
#all themes : https://sphinx-themes.org/

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

#4生成module.rst

sphinx-apidoc -f -o source/ ../module_name/

确保模块包含在module.rst 文件中 。例如 ,

sphinx-apidoc -f -o source/ ../sample_module

生成后的module.rst为

sample_module
=============

.. toctree::
   :maxdepth: 4

   main

Edit index.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

#5

make html

#6配置github页面

github page-> branch -> docs -> save

#7浏览文档地址

https://htmlpreview.github.io/?your_github_url

生成后的效果页面. https://htmlpreview.github.io/?https://github.com/iorilan/py_game_playground/blob/master/docs/html/index.html