开源python-文档撰写

python开源系列文章

• 开源Python-单元测试
• 开源python-文档撰写
• 开源python-代码规范与检查
• 开源python-打包发布
• 开源python-自动集成
• 开源python-向transformers学习

文档

整体思路：

• Sphinx 生成文档
• GitHub 托管文档
• 导入到 Read the Docs 生成在线文档

Sphinx

Mac安装

brew install sphinx-doc

安装包

pip install sphinx
pip install sphinx_rtd_theme
pip install recommonmark

进入docs文件夹，初始化的时候执行

cd docs
sphinx-quickstart

如果第一个选项输入的是yes，那么就生成如下文件夹。
source作为Sphinx的根目录，被称为source directory。按需修改其中的配置source/conf.py.
该目录中，包含配置文件conf.py，用来配置sphinx怎样读取source文件以及建立文档。
由于conf中需要recommonmark>=0.7.1包，因此加到requirements.txt里。

设置conf

例如extension

extensions = [
    "nbsphinx",
    "recommonmark",
    "sphinx_markdown_tables",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.doctest",
    "sphinx.ext.intersphinx",
    "sphinx.ext.mathjax",
    "sphinx.ext.viewcode",
    "sphinx.ext.githubpages",
    "sphinx.ext.napoleon",
]

另一个比较重要的就是主题设置

html_theme = 'sphinx_rtd_theme'

增加页面

增加其中的文档，rst，例如

 index.rst 

index可以把其他tutorial\example等页面增加到里面，增加到原本toctree后面。同时新增相对应tutorial.rst文件

.. toctree::
   :titlesonly:
   :hidden:
   :maxdepth: 6

   getting-started
   tutorials
   data
   models
   metrics
   faq
   contribute
   api
   competition
   CHANGELOG
   GitHub <https://github.com/LongxingTan/Time-series-prediction>

关于rst的格式可以参考

• https://docs.openstack.org/doc-contrib-guide/rst-conv.html
• https://docs.readthedocs.io/en/stable/tutorial/
• https://docutils.sourceforge.io/docs/user/rst/quickref.html

关于标题类

• 双下滑线代表一集标题，单下划线二级，波浪线三级
• 两个点横线，代表其他地方可以用:ref:超链过来

Tricks
======

.. _tricks:

修改完，生成文档时，mac或Linux运行make命令

make clean
make html

代码注释 annatation

• sphinx自动生成可以参考文档 https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html

• 注释规范

• vscode插件autoDocstring

实践

需要在测试都没问题后，开始生成文档。否则也会报代码的错误

本地打开网页

sphinx-autobuild source build/html

线上，最外层增加.readthedocs.yml文件，此时readthedocs,会自动根据该设置进行线上构建

https://readthedocs.org/dashboard/

中英文双语

可以参考FATE的实例，其采用的是mkdocs开源

• https://github.com/squidfunk/mkdocs-material
• https://github.com/FederatedAI/FATE/tree/master/doc

参考

• https://zhuanlan.zhihu.com/p/264647009
• https://zhuanlan.zhihu.com/p/333742823
• 工具篇-vscode效率提升插件 - 鲲China的文章 - 知乎