Sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

参考：

Sphinx初窥

  • pip install Sphinx

  • 安装完毕之后，进入任意目录运行sphinx-quickstart,进入设置向导

    1. 文档根目录(Root path for the documentation)，默认为当前目录(.)
    2. 是否分离文档源代码与生成后的文档(Separate source and build directories): y
    3. 模板与静态文件存放目录前缀(Name prefix for templates and static dir):_
    4. 项目名称(Project name) : EvaEngine
    5. 作者名称(Author name)：AlloVince
    6. 项目版本(Project version) : 1.0.1
    7. 文档默认扩展名(Source file suffix) : .rst
    8. 默认首页文件名(Name of your master document):index
    9. 是否添加epub目录(Do you want to use the epub builder):n
    10. 启用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode：n
    11. 生成Makefile (Create Makefile)：y
    12. 生成windows用命令行(Create Windows command file):y

  • 工作目录

    • Makefile：编译过代码的开发人员应该非常熟悉这个文件，如果不熟悉，那么可以将它看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
    • _build：这是触发特定输出后用来存放所生成的文件的目录。
    • _static：所有不属于源代码（如图像）一部分的文件均存放于此处，稍后会在构建目录中将它们链接在一起。
    • conf.py：这是一个 Python 文件，用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart 时选中的那些值。
    • index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。

  • 开始写作

    • source目录下创建hello.rst

      Hello World
=============

    • 修改index.rst

      在index.rst文件中的主标题之后，有一个内容清单，其中包括toctree声明。toctree是将所有文档汇集到文档中的中心元素。如果有其他文件存在，但没有将它们列在此指令下，那么在构建的时候，这些文件不会随文档一起生成。 我们想将一个新文件添加到文档中，并打算将其命名为hello.rst。还需要将它列在toctree中，但要谨慎操作。文件名后面需要有一个空格，这样文件名清单才会有效，该文件不需要文件扩展名（在本例中为 .rst）。

    • .. toctree::
:maxdepth: 2

hello

    • 根目录下命令行执行make html，再build文件夹中生成HTML

  • 主题修改

    • sphinx_rtd_theme

      sphinx_rtd_theme

    • alabaster
    • classic
    • sphinxdoc
    • scrolls
    • agogo
    • traditional
    • nature
    • haiku
    • pyramid
    • bizstyle

  • 语言支持

    • zh_CN简体中文
    • zh_TW繁体中文

托管到Read the Docs

  • 将文档项目上传至GitHub等

    因为build目录下的内容是自动生成的，所以还需要写一个.gitignore将其忽略掉。

  • 注册Read the Docs
  • 在Dashboard中创建一个新的Project，Repo中填入项目的git url。
  • 再GitHub项目设置中开启Webhooks
    • Go to the “Settings” page for your project
    • Click “Integrations & Services”
    • In the “Services” section, click “Add service”
    • In the list of available services, click “ReadTheDocs”
    • Leave “Active” checked
    • Click “Add service”

reStructuredText基础语法

一级标题
=============

二级标题
-------------

三级标题
~~~~~~~~~~~~~

* 无序列表1
* 无序列表2
* 无序列表3

#. 无序列表1
#. 无序列表2
#. 无序列表3

`链接`_

.. _链接: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/projects/tasks.py

这是 **粗体**，这是 *斜体*，注意*前有空格

.. note:: 这是蓝色注解
.. warning:: 这是红色警告

这是代码语句 ``print hello``，注意``前有空格

.. code-block:: python

    update_imported_docs(version)

+---------------+---------------+---------------+
| 表头          | 列1           | 列2           |
+---------------+---------------+---------------+
| 行1           | cell          | cell          |
+---------------+---------------+---------------+
| 行2           | cell          | cell          |
+---------------+---------------+---------------+
| 行3           | cell          | cell          |
+---------------+---------------+---------------+

添加图片，将图片放在_static文件夹中

.. image:: _static/0.jpg

results matching ""

    No results matching ""