Sphinx+github+ReadtheDocs书写笔记

举报
彭世瑜 发表于 2021/08/14 01:29:12 2021/08/14
【摘要】 项目很高端吧!废话不多说,直接来 搭建本地环境 1、确保电脑已经安装python运行环境 2、安装 sphinx及其依赖 pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables 1 3、新建文件夹,运行cmd 创建工程 sphinx-qu...

项目很高端吧!废话不多说,直接来

搭建本地环境

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

2、安装 sphinx及其依赖

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

  
 
  • 1

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

sphinx-quickstart

  
 
  • 1

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

  1. (Separate source and build directories): y
  2. 项目名称(Project name) : EvaEngine
  3. 作者名称(Author name):AlloVince

创建成功!

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

再次编译文件(同第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

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)快速入门语法说明

参考

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

  2. 写最好的文档:Sphinx + Read the Docs

  3. 使用ReadtheDocs托管文档

  4. sphinx-markdown-tables 0.0.9

文章来源: pengshiyu.blog.csdn.net,作者:彭世瑜,版权归原作者所有,如需转载,请联系作者。

原文链接:pengshiyu.blog.csdn.net/article/details/79388919

【版权声明】本文为华为云社区用户转载文章,如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。