Search code examples
python-sphinxrestructuredtextdocutils

reference sphinx |version| as monospace and no leading spaces

I'm trying to reference the sphinx |version| in a monospace block (and no spaces around it) in my .rst file like this...

You can install foo_project library with:

``pip install -U foo_project==|version|``

Cross-references with |version| outside a monospace block work just fine, but how do I make that version number show up inline with a monospaced font?

Also if I want to reference that |version| in a string like this, how do I get |version| interpolated? My use-case is:

git+https://github.com/foo_username/foo_project.git@|version|

As my rst code currently stands, |version| has to have spaces around it for it to be recognized. What should I do to fix this problem?

Solution

  • Nested inline markup is notoriously difficult (or impossible) in reStructuredText.

    You could come up with something along the lines of the following...

    In Sphinx's configuration file conf.py:

    from foo_project.__about__ import __version__

project = "foo_project"

version = f"{__version__}"

rst_prolog = f"""
.. |code_project| replace:: ``{project}``
.. |code_version| replace:: ``{version}``
.. |pip_cmd| replace:: ``pip install -U {project}=={version}``
.. |pip_git_cmd| replace:: ``pip install git+https://github.com/foo_username/{project}.git@{version}``
"""

    And in a Sphinx reStructuredText document:

    You can install the |code_project| library in its version |code_version| with one of the following commands:

* |pip_cmd|

* |pip_git_cmd|

    References: