read the docs windows 使用历程

最新推荐文章于 2025-06-05 09:07:28 发布

pourui

最新推荐文章于 2025-06-05 09:07:28 发布

阅读量700

点赞数

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/pourui/article/details/104143256

本文详细介绍在Windows环境下使用Python3及Sphinx搭建ReadTheDocs文档系统的全过程，包括配置pip源、安装Sphinx及相关插件、初始化项目、撰写文档、更改主题及预览输出等关键步骤。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

read the docs windows 使用历程

1.下载安装python3 记得勾选Addpath
2.windows下更改下载源（否则很慢），直接在user目录中创建一个pip目录，如：C:\Users\xx\pip，新建文件pip.ini，内容如下

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

3.Sphinx
Sphinx是一个基于Python的文档生成项目，最早只是用来生成 Python 官方文档，随着工具的完善，越来越多的知名的项目也用他来生成文档，甚至完全可以用他来写书采用了reStructuredText作为文档写作语言, 不过也可以通过模块支持其他格式，待会我会介绍怎样支持MarkDown格式。

安装Sphinx:

pip install sphinx sphinx-autobuild sphinx_rtd_theme

4.初始化:
直接打开最终文件保存的文件夹，复制文件路径
cmd下 cd 路径

cd C:/cs/s
 md docs     #md是mkdir的缩写，两者等价
 sphinx-quickstart

5.下面根据情况写即可

 Separate source and build directories (y/n) [n]:y
Project name: scrapy-cookbook
Author name(s): Xiong Neng
 Project release [1.0]: 0.2.2
 Project language [en]: zh_CN

6.手动添加一篇文章，在source目录下新建hello.rst，内容如下:

hello,world
=============

后修改index.rst 修改如下:

Contents:
.. toctree::
   :maxdepth: 2

   hello

注意空行

7.主题更改题为sphinx_rtd_theme
更改文件source/conf.py:
先找到html_theme这个变量进行注释#html_theme，后将下面这三行放到该变量下面保存即可

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

8.然后在cmd窗口执行 make html ，后进入build/html目录后用浏览器打开index.html 即可

9.之后操作安装这个网址里的效果图片后的步骤进行操作即可https://www.xncoding.com/2017/01/22/fullstack/readthedoc.html