include files in Sphinx

Question

Suppose, I have the following .rst file named namespace_shapes.rst:

namespace_shapes.rst

.. _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

Now, I want to split this file into namespace, class, and function files. For instance, in our case, there should be 1 file for the namespace, 1 file for the class, and 3 files for class functions.

One way to do this is to use .. include:: directive. However, this raises the following unresolvable warnings:

src/class_shapes__Square.rst:5: WARNING: duplicate label class_shapes__square, other instance in C:\Users\pc\Desktop\src\class_shapes__Square.rst
src/class_shapes__Square.rst:27: WARNING: duplicate label function__double_shapes__square__area, other instance in C:\Users\pc\Desktop\src\class_shapes__Square.rst
src/class_shapes__Square.rst:38: WARNING: duplicate label function__double_shapes__square__width, other instance in C:\Users\pc\Desktop\src\class_shapes__Square.rst
src/class_shapes__Square.rst:49: WARNING: duplicate label function__shapes__square__square, other instance in C:\Users\pc\Desktop\src\class_shapes__Square.rst

In the case of large projects, a large number of warnings cause failure to output HTML documentation.

I tried the following solutions:

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

I failed to become successful by following these solutions.

So, how can I do this?

Answer 1

Maybe the problem appears, because the included file extension are also called .rst. Try with .rest or any other file extension...

Found this solution here: https://stackoverflow.com/a/69474038/20176022

Answer 2

Move the label and its section heading out of the included file and up into the file that does the inclusion.

For example:

namespace_shapes.rst

.. _function__double_shapes__Square__width:

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

.. include:: double-width.rst

double-width.rst

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

Returns width of this square.

You would need to change the label for each instance to make it unique. It's not a great solution, but at least the duplicate label warning will not occur.

Alternatively remove labels so that they do not generate warnings. Of course that means you would lose an arbitrary reference, so not the best option.