时间戳

首页 > 解决方案 > 是否可以使用 sphinx+intersphinx 创建嵌套的 pdf 文档？

python - 是否可以使用 sphinx+intersphinx 创建嵌套的 pdf 文档？

问题描述

我有一个项目 B 需要项目 A 才能工作，所以我想将 A 的文档嵌入到 B 中，并且该文档必须是 pdf（而不是 html）。

项目 A 看起来像：

~> more conf.py
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'projectA'
copyright = '2021, JD'
author = 'JD'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

~> more .\index.rst
.. projectA documentation master file, created by
   sphinx-quickstart on Tue Jan 12 11:43:30 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to projectA's documentation!
====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   projectA

~> more .\projectA.py
#!/usr/bin/python
"""This is the documentation of project A."""

class classA:
  """This the class A."""

  def methodA(self, who):
      """This is stuff that A does."""
      return

~> more .\projectA.rst
project A
=========

.. automodule:: projectA

.. autoclass:: classA

  .. automethod:: methodA

A 的文档创建没有任何问题。

项目 B 与项目 A 处于同一级别，并且与项目 A 相同，将 A 替换为 B。

~> tree -d
intersphinx_example
|_projectA
|_projectB

但是现在，B 想使用 intersphinx 将 A 的文档包含到它自己的文档中。

~/projectB> git diff
diff --git a/conf.py b/conf.py
index 0a22df8..ac641cf 100644
--- a/conf.py
+++ b/conf.py
@@ -28,9 +28,14 @@ author = 'JD'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.intersphinx',
     'sphinx.ext.autodoc'
 ]

+intersphinx_mapping = {
+    'projA': (os.path.join('..', 'projectA'), None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

diff --git a/projectB.py b/projectB.py
index b057498..b42d485 100644
--- a/projectB.py
+++ b/projectB.py
@@ -1,10 +1,16 @@
 #!/usr/bin/python
-"""This is the documentation of project B."""
+"""This is the documentation of project B: projectB needs :ref:`projA`."""
+
+import os
+import sys
+sys.path.append(os.path.join(os.getcwd(), '..', 'projectA'))
+from projectA import classA

 class classB:
   """This the class B."""

   def methodB(self, who):
-      """This is stuff that B does."""
+      """This is stuff that B does: B need to use :ref:`projA.classA` """
+      a = classA()
       return

在 projectB 中生成文档不起作用。至少有3个问题：

我想要获得的文档是 pdf。项目（A 和 B）是 HD 上的 Python 代码（无 Web），没有与 html 相关的文档。

intersphinx 可以实现这种东西（生成嵌套的 pdf 文档）吗？超出范围了吗？

更新

也不适用于（具有相同的错误）：

~\projectB> git diff
diff --git a/conf.py b/conf.py
index 0a22df8..bc99c77 100644
--- a/conf.py
+++ b/conf.py
@@ -28,9 +28,14 @@ author = 'JD'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.intersphinx',
     'sphinx.ext.autodoc'
 ]

+intersphinx_mapping = {
+    'projA': (os.path.join('..', 'projectA', '_build'), None)
+}
+

标签： pythonpython-sphinx

解决方案

推荐阅读