使用ReadtheDocs托管文档

　　Read the Docs是一个在线文档托管服务，你可以从各种版本控制系统中导入文档，如果你使用github，那么每次提交代码后可以自动构建并上传至readthedocs网站，非常方便。

Contents

1 Sphinx
2 安装Sphinx:
3 初始化:
4 修改构建docs的配置文件
5 从代码生成rst文件
6 本地构建/预览
7 rst格式/代码文档解析

Sphinx

　　Sphinx是一个基于Python的文档生成项目，最早只是用来生成 Python 官方文档，随着工具的完善，越来越多的知名的项目也用他来生成文档，甚至完全可以用他来写书采用了reStructuredText作为文档写作语言, 不过也可以通过模块支持其他格式，之后我会介绍怎样支持MarkDown格式。

安装Sphinx:

pip install sphinx sphinx-autobuild sphinx_rtd_theme

1 2	pip install sphinx sphinx-autobuild sphinx_rtd_theme

初始化:

# 创建文档根目录
mkdir -p docs/
cd docs/
# 可以回车按默认配置来写
sphinx-quickstart

# 创建文档根目录

mkdir -p docs/

cd docs/

# 可以回车按默认配置来写

sphinx-quickstart

下面是我的配置

Separate source and build directories (y/n) [n]: y 
Project name: scrapy-cookbook Author name(s): xyu.ink 
Project version []: 0.1
Project release [1.0]: 0.1.1 
Project language [en]: zh_CN

Separate source and build directories (y/n) [n]: y

Project name: scrapy-cookbook Author name(s): xyu.ink

Project version []: 0.1

Project release [1.0]: 0.1.1

Project language [en]: zh_CN

修改构建docs的配置文件

更改source/conf.py:

# -- Project information -----------------------------------------------------
import os
import sys
dirname = os.path.dirname
rootdir = dirname(dirname(dirname(os.path.abspath(__file__))))
sys.path.insert(0, rootdir)

project = 'your_project_name'
copyright = '2020, xyu.ink'
author = 'xyu.ink'

# The full version, including alpha/beta/rc tags
release = '0.0.1'

master_doc = "index"  # 设置主页为index.rst

# -- General configuration ---------------------------------------------------
# 文档导入的python包
autodoc_mock_imports = ["torch", "torchvision", "tensorboardX", "coloredlogs", "numpy", "visdom"]


# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
]  # 扩展插件

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# 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 = []


# -- 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 = 'sphinx_rtd_theme'  # 更改html主题

html_static_path = ['_static']

# -- Project information -----------------------------------------------------

import os

import sys

dirname = os.path.dirname

rootdir = dirname(dirname(dirname(os.path.abspath(__file__))))

sys.path.insert(0, rootdir)

project = 'your_project_name'

author = 'xyu.ink'

# The full version, including alpha/beta/rc tags

release = '0.0.1'

master_doc = "index" # 设置主页为index.rst

# -- General configuration ---------------------------------------------------

# 文档导入的python包

autodoc_mock_imports = ["torch", "torchvision", "tensorboardX", "coloredlogs", "numpy", "visdom"]

# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = [

'sphinx.ext.autodoc',

'sphinx.ext.napoleon',

'sphinx.ext.doctest',

'sphinx.ext.todo',

'sphinx.ext.coverage',

'sphinx.ext.mathjax',

'sphinx.ext.viewcode',

] # 扩展插件

# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']

# 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 = []

# -- 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 = 'sphinx_rtd_theme' # 更改html主题

html_static_path = ['_static']

从代码生成rst文件

./source是index.rst所在的路径，../code/是你的代码所在的路径

sphinx-apidoc -o ./source ../code/
Creating file ./test1.rst.
Creating file ./test2.rst.
Creating file ./modules.rst.

sphinx-apidoc -o ./source ../code/

Creating file ./test1.rst.

Creating file ./test2.rst.

Creating file ./modules.rst.

本地构建/预览

运行

make html

make html

进入build/html目录后打开index.html预览。

rst格式/代码文档解析

可以使用automodule来自动发现模块。

index.rst

Welcome to torch_template's documentation!
==========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   utils

Welcome to torch_template's documentation!

==========================================

.. toctree::

:maxdepth: 2

:caption: Contents:

utils

utils.rst

Utils
======

Misc_Utils
------
.. automodule:: torch_template.utils.misc_utils
   :members:

Torch_Utils
------
.. automodule:: torch_template.utils.torch_utils
   :members:

Utils

======

Misc_Utils

------

.. automodule:: torch_template.utils.misc_utils

:members:

Torch_Utils

------

.. automodule:: torch_template.utils.torch_utils

:members: