如何在依赖于就地构建的 Python 项目中使用 Sphinx？答案

【问题标题】：How to use Sphinx in a Python project that depends on being built in place?如何在依赖于就地构建的 Python 项目中使用 Sphinx？
【发布时间】：2020-10-11 23:19:24
【问题描述】：

我有一个主要是 Python 的大型项目，我正在尝试记录它。该项目的一部分依赖于可通过 Cython 访问的 C++ 源代码。

正常运行代码时，它运行良好，但在尝试使用 Sphinx 进行自动记录时，我遇到了问题。我认为this guy 的想法是正确的，但我无法实现。

我的Makefile 看起来像这样

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".
help:
    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

如何让 Sphinx 运行 python setup.py build_ext --inplace，然后在分析代码之前引用输出 .so 文件？

感谢您的宝贵时间。

【问题讨论】：

标签： c++ makefile cython python-sphinx

【解决方案1】：

您可能希望将answer you linked 中的步骤作为从 sphinx 生成的 Makefile 的一部分添加到执行任何 sphinx 特定命令之前。

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".
help:
    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
    @cd /path/to/setup.py; python setup.py build_ext --inplace
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

将其添加到 sphinx 生成的 catch-all 命令之上意味着生成 cython 代码的 build 命令将在 sphinx 相关命令之前执行。

我建议改为将 project directory to be more standard 构建为 python 中使用的内容。不要将文档与源代码放在同一目录中，而是为源代码和文档设置一个单独的目录。

root directory/
  myproject/ (source code for Cython module)
  libs/ (generated .so files from Cython)
  tests/ (directory to hold test cases that should run after building)
    __init__.py
  docs/
    Makefile (from sphinx)
  Makefile (project)
  setup.py

项目的 Makefile 将负责构建源代码，然后构建文档。它的 Makefile 如下所示：

.all:
    @python setup.py build_ext 
    @cd tests; $(MAKE) python -m unittest
    @cd docs; $(MAKE) html

all 的第一部分将生成源代码（并且应该更新以将生成的 .so 文件放置到 libs/ 文件夹中）。第二部分将进入tests/ 目录并运行 unittests（以 python 的 unittest 库为例）。第三部分将进入docs/ 目录并使用Sphinx 生成的Makefile 为目标html 运行make。为此，您还需要更新测试和文档以在其路径中包含libs/，以便他们可以导入从构建生成的.so 文件。（注意：@ 符号可防止该行输出到控制台。如果希望将其视为构建的一部分，则应将其省略）

【讨论】：