Sphinx + Read the docs theme
The Read Theme sphinx docs
2023-09-11 14:20:09 时间
发现2个不错的中文文档:
前言:
使用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
相关文章
- Dissecting the Disruptor: How do I read from the ring buffer?
- Mysql 的异常:The last packet successfully received from the server was 90 milliseconds ago. The last packet sent successfully to the server was 43,603,303 milliseconds ago. is longer than the server con
- 【异常】[ERROR] The cloud assistant is not installed on the ECS, or the cloud assistant is unavailable. cloudassistant is uninstall
- Java实现构造无向图的欧拉回路( The Necklace)
- Database 'xxx' cannot be upgraded because it is read-only or has read-only file Make the database or files writeable, and rerun recovery.
- ArcGIS Server启动服务报:ERROR: Unable to start Xvfb on any port in the range 6600 - 6619
- [PWA] 17. Cache the photo
- [Cycle.js] Read effects from the DOM: click events
- fatal: Not a git repository (or any of the parent directories):
- [ARIA] Read error message for the focused form field by using aria-describedby
- [Javascript] Avoid Accidental Returns of New State by using the void Keyword
- [Algorithms] Classify Mystery Items with the K-Nearest Neighbors Algorithm in JavaScript
- [RxJS 6] The Catch and Rethrow RxJs Error Handling Strategy and the finalize Operator
- [AWS] Install the AWS cli
- The Query Optimizer
- The data replication requires the processing of single BDoc instances
- Unexpected XML declaration. The XML declaration must be the first node in the document and no white
- 解决The type or namespace name 'XXXX' does not exist in the namespace 'XXXXXXXXX' 的错误
- 成功解决The NVIDIA driver on your system is too old (found version 9010). Please update your GPU driver
- 成功解决TypeError: ufunc 'sqrt' not supported for the input types, and the inputs could not be safely co
- 【K3s】第25篇 解决The connection to the server localhost:8080 was refused
- The remote name could not be resolved: 'report.dalabs.cn'
- DT: An R interface to the DataTables library datatable 数据清洗
- The absolute uri: http://java.sun.com/jsp/jstl/core cannot be resolved in either web.xml or the jar
- java.lang.IllegalStateException: The specified child already has a parent. You must call removeView() on the child's parent first.
- (六)Jenkins部署项目报错The username you provided is not allowed to use the text-based Tomcat Manager (error
- 解决办法:The name 'Response' does not exist in the current context