2

I have a C API that I'm documenting using Sphinx. I'd like to have an "API Essentials" page with all the stuff most users will need, and a "Full API" page that documents absolutely everything. The trouble is, I can't find a good way to document the same function in both places. I've tried a few things already:

The naive option is to just document the function normally in both places:

essentials.rst:

.. c:function:: void foo(int arg)

   Does foo

   :param arg: Argument for foo

full.rst:

.. c:function:: void foo(int arg)

   Does foo

   :param arg: Argument for foo

This gives WARNING: Duplicate C declaration, but does sort of work. The problem (apart from the warning) is I can't pick which of the two pages is linked from cross references and the index, and Sphinx is choosing the wrong one.

The noindex option is to add :noindex: to one of them to force the index and cross references to the other. But the C domain doesn't seem to support this, because I get WARNING: Error in "function" directive: unknown option: "noindex"

There's a :noindexentry: option that is accepted, but doesn't change the behavior of the index and cross references.

The alias option is to change the function on one of the pages to an alias:

essentials.rst:

.. c:function:: void foo(int arg)

   Does foo

   :param arg: Argument for foo

full.rst:

.. c:alias:: foo

   Does foo

   :param arg: Argument for foo

This gets rid of all the warnings and makes the index and cross references correct, but the alias only shows the signature. It doesn't show the function description or parameters.

Is there any way to add duplicate documentation for a function or other C construct without affecting the original function? I'm using Sphinx 4.0.2.

Dominick Pastore
  • 4,177
  • 2
  • 17
  • 29
  • To me it looks like a bug that `:noindex:` is not supported in the C domain. The documentation does say somewhat cryptically "note that not every directive in every domain may support these options": https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#basic-markup. – mzjn Jul 05 '21 at 15:09
  • @mzjn I assume C is one of the more common domains apart from Python, so I was a bit surprised too. I guess it was just never implemented. The changelog for 3.2.0 does mention it: "C and C++, removed noindex directive option as it did nothing." This is the same version that added `:noindexentry:`. https://www.sphinx-doc.org/en/master/changes.html#release-3-2-0-released-aug-08-2020 – Dominick Pastore Jul 06 '21 at 15:25

0 Answers0