Sphinx + Readthedocs 避坑速通指南

博主在学习使用 SphinxRead the docs 的过程中, 碰到了许多奇葩的 bug, 使得很简单的任务花费了很长的时间才解决,现在在这里做一个分享,帮助大家用更少的时间高效上线文档的内容。

总的来说, 任务分为两个部分:

  • 使用 Sphinx 生成文档
  • 文档托管到 Read the docs 平台

准备

整个过程基于 python 实现, 推荐使用 Anoconda 能够创建管理独立的虚拟环境【 conda使用方法】,这样之后在配置文件的时候会方便很多。


使用 Sphinx 生成文档

掌握几个基本语句:

  1. 安装需要的库: pip install sphinx
  2. 快速创建项目:sphinx-quickstart
  3. 独立的源文件和构建目录(y/n) [n]: 个人填 y
  4. 接下来所填项目示例: 项目名称: Test

    作者名称: 摸鱼仙人

    项目发行版本 [ ]: v1

  5. 项目语种 [en]: zh_CN, 英语则填写 EN

在这之后项目基本创建完成,项目框架如图所示:

需要关注的主要是 **source** **build** 两个文件夹。

  • source : 所有的需要的文档都要放在里面 (.rst| .md)
  • build:所有生成的文件都会保存在里面

⭐ 需要配置**conf.py** **index.rst** 两个文件

powershell 复制代码
---* conf.py *---
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import sys
import os
# 此处在 sphinx-quickstart 中都进行了填写,一般无需修改
project = 'XXXX'
copyright = '2024, 摸鱼仙人'
author = 'Jin'
release = 'v1'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
# 此处为项目文件地址
project_path = "F:\XXX"
sys.path.insert(0, os.path.abspath("../.."))

# 此处为导入的 md 文件需要的配置
extensions = ['sphinx_markdown_tables', 'm2r']
source_suffix = [".rst", ".md"]


templates_path = ['_templates']
exclude_patterns = []
# 此处为项目使用语言
language = 'zh_CN'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
bash 复制代码
---* index.rst *---

.. XXXXXX documentation master file, created by
   sphinx-quickstart on Fri Mar 22 07:52:42 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

XXXXX
=========================================

.. toctree::
   :maxdepth: 3
   :caption: XXXX

    ch01_数学基础 <ch01_数学基础/ch01_数学基础.md>


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

需要熟练掌握语法, 由于内容过多, 本处不再赘述.有机会再开一篇详细展开. 配置内容大致相似,修改部分需要的名称即可.

bash 复制代码
注意:
.. toctree::
   :maxdepth: 3
   :caption: XXXX
<!-- 此处必须空一行 -->
    ch01_数学基础 <ch01_数学基础/ch01_数学基础.md>

该处的格式

掌握两句代码,反复使用:

  • make clean: 清除build生成的文件
  • make html: 生成html文件

build 文件夹 中, 可以找到 index.html, 可以通过该文件查看生成的结果


没有问题之后, 在 Github 上创建仓库, 将目前文件夹中所有的内容推送上去.

  • 配置 .gitignore 文件
bash 复制代码
---* .gitignore *---
 build/

托管到 Read the docs 平台

登录平台,使用 Github 账号进行登录

点击 导入一个项目 就可以将 Github 中的项目的文档托管过来, 以后文档的更新只需要在Github 平台上传,此处的托管能够自动的跟进更新

注意:

导入前需要创建 .readthedocs.yaml 文件进行配置, 更新上传在 Github 中

bash 复制代码
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.9"
    # You can also specify other tool versions:
    # nodejs: "19"
    # rust: "1.64"
    # golang: "1.19"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
  configuration: source/conf.py

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
#    - pdf
#    - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
   install:
   - requirements: docs/requirements.txt

点击导入后有几处地方容易导致报错, 需要注意:

  • 各个模块的内容需要顶格写,否则会出现报错

requirements.txt 文件生成:

在虚拟环境中使用 pip freeze > requirements.txt 能够自动生成配置的库的相关参数, 有时候 txt 文本中会出现一些奇怪的内容需要删除:

因此,开始时创建一个干净的虚拟环境十分有利于任务的快速推进.

导入构建后,如果显示如图则生成成功. 如果为红色, 显示 failed 则生成失败.

单击 build 则会在 构建 部分重新运行

通过此处的网址可以直接查看文档的地址:


参考资料:

  1. Sphinx + Read the Docs 从懵逼到入门
  2. 使用Read the Docs托管文档
  3. Sphinx 学习优质教程
相关推荐
轻口味2 个月前
使用sphinx自动提取python中的注释成为接口文档
开发语言·python·sphinx
林戈的IT生涯3 个月前
php连接sphinx的长连接事宜以及sphinx的排除查询以及关于sphinx里使用SetSelect进行复杂的条件过滤或复杂查询
php·sphinx·长连接事宜·sphinx排除查询·sphinx条件过滤·sphinx复杂查询
爱123哈哈3 个月前
win11使用sphinx编写文档并部署到github page
github·全文检索·sphinx
biomooc4 个月前
docs | 使用 sphinx 转化rst文件为html文档
sphinx
GuokLiu4 个月前
240707-Sphinx配置Pydata-Sphinx-Theme
python·搜索引擎·全文检索·文档·sphinx
*_潇_*4 个月前
0122__linux之eventfd理解
sphinx
LingMax20136 个月前
Mysql8 %中间%模糊搜索 强行 支持 使用 索引 代替全文搜索 全文检索数据库
sql·mysql·elasticsearch·全文检索·中文分词·solr·sphinx
ohsehun_mek07 个月前
从0到1搭建文档库——sphinx + git + read the docs
git·github·sphinx·read the docs
小松聊PHP进阶7 个月前
万字详解PHP+Sphinx中文亿级数据全文检索实战(实测亿级数据0.1秒搜索耗时)
服务器·数据库·sql·mysql·全文检索·php·sphinx