专栏首页算法与数据之美手把手教你给项目添加文档

手把手教你给项目添加文档

大家一定见过这样的文档吧?这种黑白色调看起来非常舒服,整个界面干净简洁却显得很有档次。

该文档主要是由Read the Docs这个在线文档托管、Sphinx这个基于Python的文档生成项目以及我们常逛的人类精华宝库GitHub实现的,下面我们就来梳理一下如何生成文档。

创建仓库

首先,我们需要在GitHub上创建仓库并将该仓库克隆到本地,当然你也可以直接在原有仓库上进行操作。

注册账号并连接到GitHub

接着我们需要在ReadtheDocs官网注册一个账号,https://readthedocs.org/ ,注册成功后在设置中选择已连接的服务,并点击Connect to GitHub按钮。

项目导入

在个人面板点击Import a Project,选择需要创建文档的项目,若是未找到目标项目,可以点击右上角的刷新并等待。

构建文档

导入项目之后,我们点击Build version即可成功创建文档

等待片刻后即可构建完成,Webhook自动添加之后只要更新GitHub仓库,项目文档就会自动重新构建。

然后我们就能够看到文档的雏形

添加文档

在做完上述前期工作之后,我们要来动手书写自己的文档。首先,我们需要安装Sphinx(速度较慢,建议切换成清华镜像下载),

pip install sphinx sphinx-autobuild sphinx_rtd_theme
pip install sphinx sphinx-autobuild sphinx_rtd_theme -i https://pypi.tuna.tsinghua.edu.cn/simple

接着我们进入到本地仓库目录,进行初始化,

sphinx-quickstart

可以通过一直回车来使用默认配置,在这里我主要选择了source和build目录分离,并且使用中文为项目语言。

Separate source and build directories (y/n) [n]:y
Project language [en]: zh_CN

然后我们可以通过修改source/conf.py文件来更改文档主题并添加markdown文件的支持(需要安装recommonmark)。

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

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

我们可以通过在项目根目录执行下述命令在本地生成html文件

make html

并且在build/html/index.html中来预览项目文档

最后,我们只需要修改index.rst文件便可以修改文档内容,reStructuredText 是扩展名为.rst的纯文本文件,含义为"重新构建的文本",其是轻量级标记语言的一种,被设计为容易阅读和编写的纯文本,具体如何书写可以参考下面给出的链接。

参考资料

  • Quick reStructuredText:https://docutils.sourceforge.io/docs/user/rst/quickref.html
  • Sphinx: https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html

本文分享自微信公众号 - 算法与数据之美(algo_and_data),作者:老肥

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2020-03-27

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 用Python获取可能是全网最全的杰尼龟表情包(第一弹)

    正好,我也是这沙雕网友大军中的一员,通过各种渠道收集了一些杰尼龟的表情包。但,我想要更多,只有拥有沙雕表情包最多的人才能在斗图中立于不败之地,于是便有了用Pyt...

    老肥码码码
  • 混淆矩阵及其可视化

    混淆矩阵(Confusion Matrix)是机器学习中用来总结分类模型预测结果的一个分析表,是模式识别领域中的一种常用的表达形式。它以矩阵的形式描绘样本数据的...

    老肥码码码
  • 用Python做自己的2020专属Flag动图

    2020年的开头并不顺利,有不少朋友希望能够重启2020。然而时光不可倒流,我们都应该学会积极的向前看。

    老肥码码码
  • 文本处理,第2部分:OH,倒排索引

    这是我的文本处理系列的第二部分。在这篇博客中,我们将研究如何将文本文档存储在可以通过查询轻松检索的表单中。我将使用流行的开源Apache Lucene索引进行说...

    沈唁
  • es初探

    1、ElasticSearch为了实现并发访问,每次实行更新、删除、添加之后都会为版本号自增1。

    爱撒谎的男孩
  • 关于 Blob

    对于 Blob,前端开发中可能比较少遇到;数据库中可使用 Blob 概念,例如 Mysql 存储二进制数据的类型就是 Blob,也就是说图片可存储于数据库中,以...

    Krry
  • 你不知道的 Blob

    如果你允许用户从你的网站上下载某些文件,那你可能会遇到 Blob 类型。为了实现上述的功能,你可以很容易从网上找到相关的示例,并根据实际需求进行适当的调整。对于...

    阿宝哥
  • MongoDB查询(数组、内嵌文档和$where)

    上篇主要介绍了一些基本的查询条件操作符的使用,主要针对的是一些单值,我们这次来讲讲如何查询文档内的数组和嵌入文档,并讲一下复杂查询"$where"。

    Vaccae
  • Lucene基本知识入门

    Lucene 是一套用于全文检索和搜寻的开源程序库,提供了一个简单却强大的 API,能够做全文索引和搜寻。在 Java 开发环境里,Lucene 是一个成熟的免...

    剑影啸清寒
  • 第7天: NLP——倒排表

      我们在上次介绍搭建一个智能客服系统的时候,曾经提到过得有一个语料库,这个语料库包括问题和相应的答案。当我们提出一个问题的时候,我们应该根据用户提出的问题,然...

    stefan666

扫码关注云+社区

领取腾讯云代金券