开源python-文档撰写

python开源系列文章

文档

整体思路:

  • 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-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

参考

  • 1
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

YueTann

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值