Sphinx+github+ReadtheDocs书写笔记

项目很高端吧！废话不多说，直接来

搭建本地环境

1、确保电脑已经安装python运行环境

2、安装 sphinx及其依赖

pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables

1

3、新建文件夹，运行cmd 创建工程

sphinx-quickstart

1

按照提示填写三个信息，其他一般只用填写

(Separate source and build directories): y

项目名称(Project name) : EvaEngine

创建成功！

4、编译文件

make clean # 清空 make html # 构建文档

1

2

5、打开测试，打开如下路径文件

\build\html\index.html

1

熟悉的界面，不熟悉也没关系~~~

6、更换风格

打开conf.py 文件，做如下更换

# html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme'

1

2

1

2

1

2

再次编译文件（同第4步），页面焕然一新

7、书写文章

项目文件中根目录中，新建page文件夹，新建 page.rst 文件

根据rst书写规则书写文章，例如：

新建的page页面 ================================== 这是内容

1

2

3

4

5

再次编译，访问测试

8、上传项目值github

将 整个项目 下的文件上传至github

9、 导入到 ReadtheDocs

GitHub 里选择仓库，然后依次点击 Setting => Webhooks & Service => Add service => ReadTheDocs,激活这个选项。

到 ReadtheDocs import 这个仓库，导入成功后，点击阅读文档，便可看到 Web 效果了。

遇到的问题

1、WARNING: document isn’t included in any toctree

将source/page下的所有文件包含进来

.. toctree:: :maxdepth: 2 :glob: page/*

1

2

3

4

5

2、支持markdown

打开conf.py 文件做修改

# source_suffix = '.rst' from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']

1

2

3

4

5

6

1

2

3

4

5

6

1

2

3

4

5

6

3、支持markdown的表格

pip install sphinx-markdown-tables

1

配置conf.py文件

依赖于recommonmark

extensions = [ 'sphinx_markdown_tables', ]

1

2

3

备注：

如果熟悉makedown，可以使用在线工具转为rst文档：

http://pandoc.org/try/

这是我新建的项目地址：

http://mynote-mouday.readthedocs.io

rst语法参考：

reStructuredText(rst)快速入门语法说明

参考

如何用 ReadtheDocs、Sphinx 快速搭建写书环境

写最好的文档：Sphinx + Read the Docs

使用ReadtheDocs托管文档

sphinx-markdown-tables 0.0.9

Git GitHub Sphinx

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。