使用sphinx发布python API文档到readthedocs的配置

1. 创建你的本地项目python项目。

cd your/project
pip install sphinx

2. 在项目的根目录下创建一个docs文件夹，用于存放你的文档。

cd docs
sphinx-quickstart

        2.1 在docs目录下创建一个requirements.txt。

        这个文件是用于告诉readthedocs服务器在创建Linux容器安装python环境时需要安装的项目依赖。这个文件很重要，几乎决定了你的文档会不会在readthedocs上能不能成功的生成。

        在这个文件中，你需要写明，你想让readthedocs需要的一些外部依赖，和你的python项目中使用到的所有依赖。

        

# readthedocs 需要用到的主题依赖
sphinx_rtd_theme

# python项目中要用到的依赖
pathlib
sparc_me
numpy
pandas

        如果不添加这些依赖，那么你的项目百分之九十的会遇到本地运行 make html时能生成相对应的python API文档，但是在readthedocs上却生成不了的问题。所以，一定要将你python项目中要用到的依赖全部添加到这个requirements.txt文件中。

        2.2 在docs/source目录下，配置conf.py文件

                在这个文件中，你可以配置项目文档的基本信息，作者，项目名，文档样式等。最为重要的是，你需要将你python项目的相对路径配置到readthedocs的sys路径中，这样readthedocs在运行他都服务器下运行时，才知道你的python项目在哪里，才能帮你去生成对应的API文档。这里有很多文章都会告诉你使用绝对路径来做这件事件，但是千万别这样做。虽然使用绝对路径让你在本地生成文档是没有任何问题，但是你一旦发布到reathedocs，reathedocs的服务器不可能会找到你本地项目的据对路径的，所以不要听信那些文章的胡乱建议，一定要使用相对路径来做这件事件。推荐使用pathlib来解决：

        

import sys
from pathlib import Path

current_script_path = Path(__file__)
# 得到项目的根目录
project_root = current_script_path.resolve().parent.parent.parent
# 将项目根目录添加到 readthedocs 环境中
sys.path.append(str(project_root))
# 将你python项目的相对路径添加到 readthedocs 环境中
sys.path.insert(0, str(project_root / "your"/ "python"/ "project" / "path"))

                比如，我的python项目在与docs同级目录下， 名为my_project文件夹，

        

import sys
from pathlib import Path

current_script_path = Path(__file__)
project_root = current_script_path.resolve().parent.parent.parent
sys.path.append(str(project_root))
sys.path.insert(0, str(project_root / "my_project"))

                其余的项目信息相关的配置，自己随便根据自己的需求来填就行啦。

        2.3 在docs目录下运行生成文档.rst的脚本

sphinx-apidoc -o source ../my_project

         2.4 在本地docs目录运行 make html 来检查生成的文档

        

# Mac os and Linux

make html

# windows

./make html

                运行后，它会自动生成一个build文件夹在docs中。

cd build/html

live-server

# 如何没有live-server， 建议安装个node js

# npm install -g live-server

                 然后你就可以在本地查看你生成的文档是否正确， 如果全部都符合你的要求，那么，你就可以在readthedocs上发布你的文档了。

 3 发布文档到readthedocs通过GitHub

        3.1 配置 github

                在根目录中，创建一个 .readthedocs.yaml 文件， 这个文件是连接readthedocs和GitHub的webhook文件。

# .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: docs/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

                在这个文件里面告诉readthedocs，你需要的是什么python版本，你的sphinx配置文件在哪里，以及最重要的你的项目依赖requirements.txt文件在哪里。

        3.2 将你的代码发布到GitHub仓库

        3.3 登陆readthedocs官网，通过GitHub账号来登陆

        3.4 在readthedocs网站中，导入你的代码仓库，注意这里你可以选择仓库的分枝branch。

        3.5 build 你的项目文档。

1～2分钟之后你就可以在浏览器中，查看你的python API文档了。