CODEWITHSUNDEEP
pythonpython-sphinxsubstitution
marco
marco

Reputation: 11

Python Sphinx/rest substitution for long names defining substitution rule in same source file

Post Python Sphinx referencing long names provided one answer that was very close to what I was looking for with regards to substitution directives for long class names.

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    .. |ReallyLongExampleClassName| replace:: 
                                    :class:`.ReallyLongExampleClassName`

In the example provided however, the definition for replacement rule is within the same pydoc block. I was hoping to do something like this:

"""define all rst links/substitutions used in this file
.. |ReallyLongExampleClassName| replace:: :class:`.ReallyLongExampleClassName`
.. |AnotherExampleClassName| replace:: :class:`.AnotherExampleClassName`
"""

# more code
# more code


def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    # define function

Since every file in question is specific, the use of the rst_epilog doesn't extend very well. Is this even possible.

Upvotes: 1

Views: 380

Answers (1)

Phil
Phil

Reputation: 6184

You can do that with the variable rst_epilog in your conf.py file. This is taken straight from rst_epilog:

rst_epilog

A string of reStructuredText that will be included at the end of every source file that is read. This is the right place to add substitutions that should be available in every file. An example:

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

But you say that rst_epilog is not a good fit for your use case. Perhaps the rst include directive is a better approach? You can put your commonly used substitutions into a single rst document and include it in the documents where you need to use them.

Upvotes: 1

Related Questions