How to print the document version in the title?

Question

I've just created a Sphinx doc using sphinx-quickstart.exe with alabaster theme.

And I would like to print the version of the document somewhere in the title.

I filled version and release variables in conf.py

# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.

# -- Project information -----------------------------------------------------

project = 'MWE'
copyright = '2019, and1er'
author = 'and1er'

# The short X.Y version
version = '2.4.12'
# The full version, including alpha/beta/rc tags
release = 'beta'

extensions = [
]

templates_path = ['_templates']
source_suffix = '.rst'

master_doc = 'index'
language = None
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'

html_theme = 'alabaster'

html_static_path = ['_static']
htmlhelp_basename = 'MWEdoc'

index.rst

.. MWE documentation master file, created by
    sphinx-quickstart on Tue Feb  5 14:51:07 2019.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.

Welcome to MWE's documentation!
===============================

.. toctree::
    :maxdepth: 2
    :caption: Contents:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Resulting document does not have 2.4.12 or beta strings.

score 4 · Accepted Answer · edited Feb 05 '19 at 15:51

4

Does |version| substitution works for you?

UPD An updated MWE

index.rst

.. MWE documentation master file, created by
   sphinx-quickstart on Tue Feb  5 14:51:07 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to MWE's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Document version:
|version|
|release|


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

edited Feb 05 '19 at 15:51

and1er

749
8
18

answered Feb 05 '19 at 12:08

Slam

8,112
1
36
44

Yes, that's actually I need! It was not clear to me how to find this in Sphinx documentation and called _Substitutions_. BTW, there is noted _The documentation system provides three substitutions that are defined **by default**. They are set in the build configuration file._ And no any link how to create additional substitutions. – and1er Feb 05 '19 at 12:19
@and1er there is documentation on substitutions. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions which includes a reference to the underlying reST reference http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions – Steve Piercy Feb 05 '19 at 12:29
@StevePiercy, as I understand substitutions are about definitions for a text and markup pieces (like `\newcommand{}` in TeX) but substitutions cannot insert other python variables from `conf.py` beside `version`, `release` and `today`, right? – and1er Feb 05 '19 at 12:48
What happens when you try creating other Python variables in your `conf.py`? – Steve Piercy Feb 05 '19 at 15:17
@StevePiercy, for example in `conf.py` I set `foo_var = 'bar value'`, then in `index.rst` try `|foo_var|`. The result: in HTML a following text (as hyperlink) is printed: `|foo_var|` – and1er Feb 11 '19 at 14:27
I think you missed something. That docs section also includes links to [`rst_prolog`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog) and [`rst_epilog`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog). That works for me. – Steve Piercy Feb 11 '19 at 17:08

Steve Piercy · Answer 2 · 2019-02-05T15:28:39.310

1

In addition to the substitution as @Slam mentioned, you can avoid updating this setting manually for each release in your project's conf.py.

import pkg_resources
version = pkg_resources.get_distribution('myproject').version
release = version

Then |release| can be placed in your reST source files or {{ release }} in your theme's templates.

edited Feb 05 '19 at 15:28

answered Feb 05 '19 at 12:41

Steve Piercy

13,693
1
44
57

should I create a custom Sphinx theme to use `{{ release }}` variable to put the value from python code? – and1er Feb 05 '19 at 12:54
1

Either that or you could append it to another variable in your `conf.py` which is already defined in your theme. For example: `html_title = 'My Project v%s' % release` – Steve Piercy Feb 05 '19 at 15:29

How to print the document version in the title?

2 Answers2