Transclude function documentation into page in sphinx

Question

I have a medium-sized python project that I'm currently documenting using sphinx with the autodoc extension. I have the basics down, the generated documentation looks reasonable.

I have now come across an interesting documentation problem: I have some JSON input file that contains configuration of some sorts. It contains several sections that are used in different parts of my application. I figured the best way to keep the documentation up to date is to document configuration options as close to the point of their usage as possible.

On the other hand, I'd really like to have a single page describing the complete input file structure.

I figured it would be nice if I could somehow "transclude" the relevant documentation blocks into this page so that it shows up both in this page and within the respective module documentation pages like so:

a.py:

def fn_using_A():
  '''documentation for config parameter paramA
  '''
  pass

b.py

def fn_using_B():
  '''documentation for config parameter paramB
  '''

The input file format documentation page should look somewhat like this:

paramB
------

documentation for config parameter paramB


paramA
------

documentation for config parameter paramA

I would like to not have links/references to the respective functions/modules/whatever but a verbatim copy of the documentation without having to actually copy the documentation into the respective .rst file.

It would be even better to only transclude a part of the documentation I can mark somehow within my code documentation.

I tried using reST's replace feature, writing

def fn_handling_C():
  '''fn documentation

  .. |paramC_documentation| replace:: foo bar baz
  '''

in my code and using |paramC_documentation| within the .rst file that documents my input file format, but generating the documentation yields an error message to the effect that the replacement pattern isn't known. That doesn't surprise me since autodoc doesn't generate full .rst files for modules which are parsed together with manually written .rst files.

Is there a way to achieve this with sphinx?

Answer 1

I ended up writing my own sphinx extension. I used sphinx-todo as basis and modified that to my liking.