优雅的写文档

优雅的管理文档

摘要

typora编写markdown文档，用Sphinx管理，使用github进行版本管理，在readthedocs生成网页。

typora&markdown

自行查找使用方法

Sphinx

Sphinx 是一个工具，它使得创建一个智能而美丽的文档变得简单。作者Georg Brandl，基于BSD许可证。

起初为写 Python 文档而诞生的 Sphinx，支持为各种语言生成软件开发文档。

它有着以下突出特性：

• 输出格式：HTML（包括Windows的HTML帮助文件）、LaTex（可以打印为PDF）、epub（流行的电子书格式）、Texinfo、manual pages（man手册）、plain Text（纯文本）
• 广泛的交叉引用：语义标记，函数、类等的自动连接等
• 分层架构：目录树的简单定义，有自动链接的父子兄弟节点等
• 自动索引
• 代码高亮
• 丰富的拓展

Sphinx 使用 reStructuredText 作为编写语言，也可以使用 Markdown + 拓展库的方式进行文档的编写。

安装

• 安装python3
• 通过python安装sphinx
• 安装requirements.txt依赖包

1. 安装python3

   从https://www.python.org/网站下载python3最新版本（不要用python2）

   我们这里用的是win10操作系统，所以选择对应的版本安装。（Linux请自行查找安装方法）

   

   安装时记得把环境变量勾上。

   

   安装结束后打开电脑命令行，输入python。正常就可以看到版本信息，不正常通常就是环境变量没勾上。

   

2. 安装sphinx

   通过python的pip安装。

   pip install sphinx sphinx-autobuild sphinx_rtd_theme
   

    

   如果直接安装太慢，可以指定清华大学的源

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

    

   执行pip指令前先用exit()退出puthon交互界面。

   

3. 创建模板

   安装结束后，我们就可以创建一个模板了。首先在电脑创建一个文件夹。例如H盘创建sphinx_demo。

   在命令行中跳到这个文件夹内。输入sphinx-quickstart，执行创建模板，输入信息见下图。

   

   此时在文件夹内有build、source两个文件夹和make.bat、Makefile两个文件。

   build文件夹是编译后的文件，可以随时删除，编译后重新生成。

   source则是源文件目录。

4. 配置模板

   还需要对模板进行配置才能使用。

   首先安装依赖，依赖用于支持markdown、markdown表格、主题。

   在sphinx_demo目录下创建requirements.txt文件，文件内容如下

   ​x
   recommonmark
   sphinx-markdown-tables
   ​
   #theme
   ​
   #crate-docs-theme
   sphinx-rtd-theme
   ​
   

    

   这些依赖也可以直接用python pip安装，但是如果你要在readthedocs上管理文档，就需要通过创建requirements.txt的方式安装。

   在命令行窗口执行下面指令安装依赖，

   xxxxxxxxxx
   py -3 -m pip install -r requirements.txt
   

    

   如果很慢或者失败，也可以用清华的源。

   xxxxxxxxxx
   py -3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

    

   修改source/conf.py

   xxxxxxxxxx
    -- Project information -----------------------------------------------------
   ​
   project = 'sphinx_demo'
   copyright = '2019, wujique'
   author = 'wujique'
   ​
   # The full version, including alpha/beta/rc tags
   release = '0.0.1'
   ​
   ​
   # -- General configuration ---------------------------------------------------
   ​
   # Add any Sphinx extension module names here, as strings. They can be
   # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
   # ones.
   extensions = ['recommonmark',
     'sphinx_markdown_tables',
   ]
   # Add any paths that contain templates here, relative to this directory.
   templates_path = ['_templates']
   ​
   # The language for content autogenerated by Sphinx. Refer to documentation
   # for a list of supported languages.
   #
   # This is also used if you do content translation via gettext catalogs.
   # Usually you set "language" from the command line for these cases.
   language = 'zh_CN'
   ​
   # List of patterns, relative to source directory, that match files and
   # directories to ignore when looking for source files.
   # This pattern also affects html_static_path and html_extra_path.
   exclude_patterns = []
   ​
   #supported markdown
   source_suffix = ['.rst', '.md']
   ​
   master_doc = 'index'
   ​
   # -- Options for HTML output -------------------------------------------------
   ​
   # The theme to use for HTML and HTML Help pages.  See the documentation for
   # a list of builtin themes.
   #
   #html_theme = 'alabaster'
   import sphinx_rtd_theme
   html_theme = "sphinx_rtd_theme"
   html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
   

    

   project = 'sphinx_demo':这个是项目名称，会在生成的网页上显示，根据需要修改。

   master_doc = 'index'：这个指定了入口，在readthedocs中需要。

   其他的修改为markdown和主题配置。

5. 添加内容

   可以在soure中添加目录用于保存添加的markdown文档。我们添加sphinx文档，并在里面添加sphinx.md文件（就是现在看到的文件）。

   然后修改index.rst

   xxxxxxxxxx
   .. sphinx_demo documentation master file, created by
      sphinx-quickstart on Sun Mar  8 09:46:27 2020.
      You can adapt this file completely to your liking, but it should at least
      contain the root `toctree` directive.
   ​
   欢迎使用 sphinx_demo's documentation!
   =======================================
   ​
   .. toctree::
      :maxdepth: 1
      :caption: 优雅的写文档:
      
      sphinx/sphinx
   ​
   ​
   ​
   Indices and tables
   ==================
   ​
   * :ref:`genindex`
   * :ref:`modindex`
   * :ref:`search`
   

    

   一列等号上的是标题，申城的html网页会看到。

   中间这段是主题，一个sphinx可以有多个主题。

   xxxxxxxxxx
   .. toctree::
      :maxdepth: 1
      :caption: 优雅的写文档:
      
      sphinx/sphinx
   

    

   maxdepth指定目录显示的标题深度，通常选择1。

   caption是主题的名称。

   空一行，紧跟着就是这个主题包含的源文件。

   文件（源文件、conf.py等）的格式必须是utf-8 无bom格式，否则会出错

6. 编译

   执行make.bat html指令编译文件。

   

   成功后查看build目录，在html文件夹中有一个index.html文件，用浏览器打开。done

   

Github托管

自学

ReadtheDocs托管

带补充

可参考：

《使用ReadtheDocs托管文档》

https://www.xncoding.com/2017/01/22/fullstack/readthedoc.html

其他

1. 注意文档格式。一定要是utf-8 无bom格式
2. 注意图片名称要一致。在typora中，不区分大小写，在readthedocs中大小写一定要匹配
3. 要修改cotent.c（readthedoc构建错误，具体细节忘了）

END

2020-03-08