Read the Docs @python

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you. Think of it as Coninuous Documentation.

概述

Read the Docs如前言所述,主要是用来简化软件的文档工作,支持自动构建、版本控制及文档托管。可以将之考虑为持续文档,支持以下特点:

  • Never out of sync: 同步,一时不停;
  • Multiple versions: 多版本控制;
  • Free and open source: 免费开源。

婴儿学步

Read-the-Docs支持SphinxMkDocs,此处仅介绍MkDocs

Getting started with MkDocs

MkDocs是一个集中速度与简洁的文档生成器。它具有如下特点:

  • 边编写边预览;
  • 主题和扩展易于扩展;
  • 文档使用Markdown语法。

Quick Start

  1. 安装MkDocsconda install mkdocs
  2. 部署MkDocs项目:mkdir demo && mkdocs new .;其中,mkdocs.ymlMkDocs配置文件,docs/index.md是文档的入口;
  3. 启动开发服务器:mkdocs serve

当修订好文档后可以参阅内容Importing your existing documentation
External Resources,下列是一些相关资源:

Importing your existing documentation

导入公共文档仓库的内容,可以访问Read the Docs dashboard并点击Import。私有的文档仓库请使用Read the Docs for Business

如果我们将账号关联到Github/Bitbucket/GitLab的话,就可以直接导入一些公共文档仓库。

Manually Import Your Docs: 倘若没有关联账号,则需要手动导入文档仓库,细节参见原文。
Building Your Documentation:完成导入文档的过程之后,文档代码将被自动导入并构建;构建的细节请参见Build Process;配置信息可在readthedocs.yml中进行制定,规则参见Configuration File;版本控制的功能参见Versions;帮助信息可参见Support

入门指南

该部分介绍Read the Docs的一些核心功能、常用配置、版本控制等。

Overview of core features

该部分主要是罗列Read the Docs的核心特征。

GitHub, Bitbucket and GitLab Integration:支持这三个平台的集成,参见Version Control System Integration
Auto-updating:借助Webhooks可以自动构建文档;
Internationalization:支持多语言,更多信息参见Localization of DocumentationInternationalization
Canonical URLs:支持经典URLs,更多信息参见Canonical URLs
Versions:支持多版本文档;
Version Control Support Matrix:此处主要看Git这块,支持tags/branches,默认分支为master
PDF Generation:当使用RTD时,亦可生成PDF文档;
Search:支持全文搜索;
Alternate Domains:支持自定义域名、子域名及shorturl,详情参见Custom Domains

Configure your documentation

Connecting with Github, BitBucket, or GitLab

Read the Docs build and versioning process

Troubleshooting - Support

Troubleshooting - Frequently asked questions

高级特性

这部分还没怎么用着,先罗列如下:

参考资料

@ReadTheDocs

0%