Sphinx + Read the docs theme
2024-09-06 05:10:40
前言:
使用Sphinx 生成文档和使用 Read The Docs 的 readthedocs/sphinx_rtd_theme,假设是在Windows上运行并已安装好 python,可以执行python的 pip
命令
- 通过 pip命令安装 sphinx 和 sphinx_rtd_theme
pip install -U Sphinx
pip install sphinx-rtd-theme
- 在一个系统中的一个空的文件夹中运行: 如我在D 盘中新建了一个名字为
sphinx
的文件夹
sphinx-quickstart
D:\>mkdir sphinx-study
D:\>cd sphinx-study
D:\sphinx-study>sphinx-quickstart
Welcome to the Sphinx 2.2.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: Study
> Author name(s): wakasann
> Project release []: 1.0.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN
Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
D:\sphinx-study>
从上面的末尾的提示,可以看到,可以通过make builder
来编译文档,builder
是如html
,latex
或者linkcheck
其中的一个支持的编译器。
如命令: make html
是生成html格式的文档
- 在Sphinx项目中使用sphinx-rtd-theme主题,将下面的配置项加到
conf.py
文件中
import sphinx_rtd_theme
extensions = [
...
"sphinx_rtd_theme",
]
html_theme = "sphinx_rtd_theme"
来自 Read the Docs Sphinx Theme的README.md的说明
- 生成 html 格式的文档
命令行 进入 Sphinx 项目,运行
make html
or
make.bat html
如果需要发布到 RTD官网
- 编译失败,如在编译时遇到以下错误
Sphinx error: master file [..]/checkouts/latest/contents.rst not found
修复方法是: 修改 sphinx项目的conf.py
添加以下的一行:
master_doc = 'index'
References
- 技术文档编写利器:Sphinx+Read the Docs
- Getting Started
- Read the Docs Sphinx Theme
- Sphinx error: master file ../checkouts/latest/contents.rst not found
- Removing “Edit on …” Buttons from Documentation 隐藏RTD上的 "Edit on Github"信息
最新文章
- webstorm官网最新版激活:
- 跟着鸟哥学Linux系列笔记3-第11章BASH学习
- 两个不等式(Nopier)
- linux.打包与压缩
- MVC&;&;MVP
- 第一天CSS实战培训及笔记及感想
- Lamp环境部署指南
- 页面加载完成,但ie进度条一直加载
- python之6-1常用函数
- 【点击模型学习笔记】Predicting Clicks_Estimating the Click-Through Rate for New Ads_MS_www2007
- Oracle 取上周一到周末日期的查询语句
- Swift - 实现拨打电话
- Java调用IIS发布的WebService
- 【硬件】DELLserver硬件监控和DELL系统管理工具OMSA介绍
- 阿里云服务器+ftp文件操作+基于Centos7的vsftpd配置
- 最小生成树(Prim算法)
- Windows上IOCP Socket事件模型管理
- LeetCode 908 Smallest Range I 解题报告
- .net中几个经常用到的字符串的截取
- Delphi 变体数组 Dataset Locate 查找定位
热门文章
- 【串线篇】MVC与SpringMVC
- Qt pro使用sql之类的需要添加的模块
- ELK Stack 7.1.1之集群搭建
- Django中object.all是什么东西
- Branch policies on Azure Repos
- 框架-.NET:.NET Core
- mybatis中Parameter index out of range (2 >; number of parameters, which is 1).
- openlayers中单击获取要素
- 27. Unittest单元测试框架的介绍与使用
- 搭建RAID5(5块硬盘)过程并模拟一块磁盘损坏情况