No version shown

Bug #1843976 reported by Andreas Jaeger on 2019-09-14
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Stephen Finucane

Bug Description

A document should show the version - but several projects don't anymore like
octavia-dashboard and even openstackdocstheme.

Somehow the variable version is set to "" and thus nothing is build.

See for my hacky solution. Something strange is happening here that sets version.

See and

Is this a sphinx regression?

Changed in openstack-doc-tools:
importance: Undecided → Critical

This is fun. It's not a Sphinx regression so much as a difference in behavior between how the 'build_sphinx' distutils command works and how the 'sphinx-build' command works. Looking at openstackdocstheme itself, I note that the version disappears between 1.22.0 and 1.23.0. Nothing jumps out except for this diff:

    $ git diff 1.22.0..1.23.0
    diff --git a/tox.ini b/tox.ini
    index 318d788..c638efb 100644
    --- a/tox.ini
    +++ b/tox.ini
    @@ -29,15 +29,12 @@ commands = {posargs}
     basepython = python3
     commands =
       rm -rf doc/build api-ref/build
    - python build_sphinx
    - sphinx-build -a -E -W -d doc/build/doctrees -b latex doc/source doc/build/pdf
    - make -C doc/build/pdf
    - sphinx-build -a -E -W -d api-ref/build/doctrees -b html api-ref/source api-ref/build/html
    + sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html

     commands =
       rm -rf doc/build api-ref/build
    - python build_sphinx
    + sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
       sphinx-build -a -E -W -d api-ref/build/doctrees -b html api-ref/source api-ref/build/html


Indeed, building the docs via '' restores the version:

    $ source .tox/docs/bin/activate
    $ python build_sphinx

And here's why - the distutils extension explicitly sets the version to None:

While the config default is the empty string:

The empty string is the thing we're using to indicate that we should not automatically include the version in the docs:

I guess we need a breaking change to use a known string that indicates we shouldn't add the version. That or a config option.

Changed in openstack-doc-tools:
status: New → Confirmed
assignee: nobody → Stephen Finucane (stephenfinucane)

Fix proposed to branch: master

Changed in openstack-doc-tools:
status: Confirmed → In Progress
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers