在 Sphinx 中包含文件

编程问答 2022-04-23

问题描述

假设我有以下名为 we recommend 133 conversion action(s) 的 .rst 文件：

namespace_shapes.rst

namespace_shapes.rst

现在，我想将此文件拆分为命名空间、类和函数文件。例如，在我们的例子中，命名空间应该有 1 个文件，类应该有 1 个文件，类函数应该有 3 个文件。

一种方法是使用 .. _namespace_shapes: ====== shapes ====== namespace ========= Class Summary ============= +---------------------------------------------------+-------------------------------+ | :ref:`shapes::Square<class_shapes__Square>` | Represents a square. | +---------------------------------------------------+-------------------------------+ .. _class_shapes__Square: ============== shapes::Square ============== class ===== Method Summary ============== +-----------------------------------------------------------------------------------------+-----------------------------------------+ | :ref:`area () const<function__double_shapes__Square__area>` | Returns area of this shape. | +-----------------------------------------------------------------------------------------+-----------------------------------------+ | :ref:`width () const<function__double_shapes__Square__width>` | Returns width of this square. | +-----------------------------------------------------------------------------------------+-----------------------------------------+ | :ref:`Square (const std::string &id,const double a)<function__shapes__Square__Square>` | Constructor sets fields of this object. | +-----------------------------------------------------------------------------------------+-----------------------------------------+ .. _function__double_shapes__Square__area: double area() const =================== virtual double shapes::Square::area () const -------------------------------------------- Returns area of this shape. .. _function__double_shapes__Square__width: double width() const ==================== double shapes::Square::width () const ------------------------------------- Returns width of this square. .. _function__shapes__Square__Square: Square(const std::string &id,const double a) ============================================= shapes::Square::Square (const std::string &id,const double a) -------------------------------------------------------------- Constructor sets fields of this object. idid string of this shape aside width 指令。但是，这会引发以下无法解决的警告：

.. include::

在大型项目的情况下，大量警告导致无法输出HTML文档。

我尝试了以下解决方案：

  1. Get rid of "duplicate label" warning in Sphinx
  2. Sphinx's .. include:: directive and "duplicate label" warnings

我未能通过遵循这些解决方案获得成功。

那么，我该怎么做？

解决方法

将标签及其部分标题从包含的文件中移出，并向上移到进行包含的文件中。

例如：

namespace_shapes.rst

.. _function__double_shapes__Square__width:

double width() const
====================

.. include:: double-width.rst

双倍宽度.rst

double shapes::Square::width () const
-------------------------------------

Returns width of this square.

您需要更改每个实例的标签以使其唯一。这不是一个很好的解决方案，但至少不会出现重复标签警告。

或者删除标签，这样它们就不会产生警告。当然，这意味着您会丢失任意引用，因此不是最佳选择。

python-sphinxrestructuredtext