如何使用ReadtheDocs和GitHub免费托管文档

readthedocs示例

说起IT这行业,经常看的就是docs,一个模块或者一个框架如何使用,最好的使用说明就在官方的文档中,而不是通过CSDN等平台去找答案。对于作者或者某些好心的志愿者来说,免费的好用的文档托管平台——readthedocs是最好的选择,这里我们用到的是GitHub+ readthedocs ,你也可以选择gitlab或者其他版本管理仓库,有了GitHub,可以利用Webhooks实时监控更新,并且可以进行文档的版本管理。

首页我们需要在本地写好文档,然后上传到GitHub,再在 readthedocs 中关联GitHub中资源即可。

Sphinx 本地环境搭建和编写文档

pip install sphinx  # 安装sphinx

sphinx是使用最广泛的文档框架,快速生成文档资源,是基于python环境的模块,这里你需要拥有python3.6以上的环境。

pip install sphinx_rtd_theme # 安装readthedocs主题

本主题图一示例的主题,也是比较常见的,而默认的是flask官方文档的主题,这里建议使用sphinx_rtd_theme主题。我们需要在conf.py中将主题改为sphinx_rtd_theme。

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# html_theme = 'alabaster' # 这里注释掉

开始创建

sphinx-quickstart

这个命令可以快速创建文档的,这里需要填写一些文档的信息,包含版本、名称、作者和语言等等。

> Separate source and build directories (y/n) [n]:y
> Project name: scrapy-cookbook
> Author name(s): Xiong Neng
> Project version []: 0.2
> Project release [1.0]: 0.2.2
> Project language [en]: zh_CN

文档结构如下:

.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

这里网页的内容在source中,默认是rst结尾的文件,这种文档的编写不如markdown好写,这里我们需要将rst文件转换为md文件,并以markdown形式的语法编写语言。这里需要安装markdown模块

pip install recommonmark

并在conf.py中添加

from recommonmark.parser import CommonMarkParser
source_parsers = {
    '.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

到这里的,我们可以创建md的文件,这里我们在source中创建文件——test.md

# title1
## title2

然后我们在index.rst中将test章节加入到主页

.. toctree::
   :maxdepth: 2

   test

本地预览

我们完成以上之后,执行命令 make html ,然后会在build中生成html文件夹,其中包含index.html,我们可以在本地预览了。

注意事项

当我们预览时,会发现

readthedocs 示例

这里左侧的列表一级标题,主页限制的是所有标题,但是对于文件比较多的文档来说,这样会显示十分的混乱,这里我们需要让左侧显示每一个文件的标题。

这里我举个大佬的例子

我们观察他的主页文件

这里我们可以看到 chapter/* 表示要包含chapter目录中的所有文件

而chapter目录中的每一个rst文件又是一个包含很多rst文件的目录

这里包含的是c01目录中的所有文件

上传项目到GitHub中

这里我们需要上传的是不用包含build目录的其他文件,这里需要注意的是需要利用pip freeze > requirements.txt 生成配置文件

发布到 readthedocs

  1. 注册 readthedocs 账号 ,https://readthedocs.org/ 用GitHub账号关联登录即可
  2. import导入GitHub中的项目
  3. 上传之后,会自动构建并且发布
  4. 高级配置中我们可以选择python的版本,现在默认的是3.0的版本,也可以指定requirements.txt,不指定的话,系统构建工具会自动查找。
赞(0) 打赏
未经允许不得转载:karl_科技站—专注网络技术 » 如何使用ReadtheDocs和GitHub免费托管文档

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

商务合作

联系我们

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏