2024-02-06 Sphinx学习笔记

WARNING: This article may be obsolete
This post was published in 2024-02-06. Obviously, expired content is less useful to users if it has already pasted its expiration date.

This article is categorized as "Garbage" . It should NEVER be appeared in your search engine's results.

很零散也很混乱，因为各种相对路径错误/index错误/chatgpt乱回答浪费了很多时间。

目前看下来sphinx用pip安装就可以：

pip3 install sphinx

参考了一部分，但有些地方不一样：🔗 [markdown - Python docstrings to GitHub README.md - Stack Overflow] https://stackoverflow.com/questions/36237477/python-docstrings-to-github-readme-md

之前学习的过程中遇到的很头痛的问题就是如何exclude特定文件，或者干脆如何include指定文件，但一直没解决，所以最后的解决方案就是：

直接建一个新的项目专门处理sphinx，然后把想要include的那几个.py文件复制过去

首先这个命令：

sphinx-apidoc -o Sphinx-docs . sphinx-apidoc --full -A 'Matteo Ferla'; cd Sphinx-docs;

然后（和stackoverflow的回答相反）这段代码需要添加到Sphinx-docs/conf.py开头：

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

注意：如果某些.py文件中有类似这样的文件读取路径：

./data/data1.csv

在执行sphinx build的时候就会出问题（找不到./data/data1.csv），这个时候需要把data文件夹拷贝到Sphinx-docs文件夹下（而不是上一层存放python文件的目录）

最后（在Sphinx-docs目录下）

mkdir build

sphinx-build -b html ./ build

更新了.py文件以后只需要执行最后一条命令sphinx-build -b html ./ build就可以，不需要重复前面的动作

补充一些优化/定制：

自带的太难看了

换个主题：

🔗 [Sphinx Themes Gallery] https://sphinx-themes.org/#themes

注意：换主题后建议删除build文件夹所有文件重新构建，否则可能会出现主题混乱的情况

解决epytext问题

epytext是一种docstring风格，pycharm似乎会默认提供这个，但Sphinx默认不会解析epytext，这就导致那些 @param 不会被识别，非常难看

解决方法是装个插件：🔗 [sphinx-epytext · PyPI] https://pypi.org/project/sphinx-epytext/

默认是不会给__init__()的docstring生成文档的

让__init__()的docstring也加进来：🔗 [python - How to use Sphinx's autodoc to document a class's init(self) method? - Stack Overflow] https://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method