Sphinx文档书写(Sphinx+gitee+read the Docs)

Sphinx文档书写(Sphinx+gitee+read the Docs)

1 创建文件夹 ,例如MYDOCS

2 安装sphinx，首先确保安装了python和pip。

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

3 当前目录下打开终端，命令：sphinx-quickstart

4 编译，终端输入 .\make html

5 sphinx-autobuild 编译

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild #安装
sphinx-autobuild source .\build\html  #编译文件

 然后可以使用终端输出的ip地址和端口号进行访问，效果同上。

6 主题更改

 Sphinx主题官网:https://sphinx-themes.org/
 随便点一个主题，进入按照说明安装，例如：

pip install sphinx-rtd-theme

 修改conf.py 文件

html_theme = 'sphinx_rtd_theme'

 重新编译后，可以看到主题更新了~

7 markdown支持

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple recommonmark
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx_markdown_tables

 修改conf.py 文件extensions = ['recommonmark','sphinx_markdown_tables']

8 markdown编写

 可参考官网。

9 gitee推送

  如果前面使用了extensions = ['recommonmark','sphinx_markdown_tables']这两个markdown插件需要多做两件事情：
（1） 根目录创建.readthedocs.yml，内容为：

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: source/conf.py  # 这个路径根据`conf.py`的路径写，一般放在source目录


# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF
formats:
  - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
  version: 3.7
  install:
    - requirements: requirements.txt   # 这个路径根据`.requirements.txt`的路径写，一般放在根目录

（2） 根目录创建.requirements.txt，内容（根据使用的插件添加）为：

sphinx
sphinx-rtd-theme
recommonmark
sphinx_markdown_tables

 将MYDOCS文件夹下（build文件夹下可不推送）的内容推送到gitee，使用tortoisegit比较方便。注意：gitee仓库需要是公开的。

10 Read the Docs

Read the Docs官网。我的项目->Import a Project->手动导入->填写gitee仓库信息和项目名称->构建->最终可以点击阅读文档进行访问。可能构建会出错，把conf.py文件中的extensions = ['recommonmark','sphinx_markdown_tables']改为extensions = ['recommonmark']

最后

  当然，书写文档的工具有很多，例如Hexo，Mkdocs，Teadocs，大同小异，只是他们依赖的语言环境不同。仓库也可以使用github，gitlab等进行托管。