No version shown

Bug #1843976 reported by Andreas Jaeger on 2019-09-14
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
openstack-doc-tools
Critical
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
https://review.opendev.org/#/c/682193/ for my hacky solution. Something strange is happening here that sets version.

See https://docs.openstack.org/openstackdocstheme/latest/ and
https://docs.openstack.org/nova/latest/

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 setup.py 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

     [testenv:html]
     commands =
       rm -rf doc/build api-ref/build
    - python setup.py 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

     [testenv:releasenotes]

Indeed, building the docs via 'setup.py' restores the version:

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

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

https://github.com/sphinx-doc/sphinx/blob/v2.2.0/sphinx/setup_command.py#L80

While the config default is the empty string:

https://github.com/sphinx-doc/sphinx/blob/v2.2.0/sphinx/config.py#L105

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

https://github.com/openstack/openstackdocstheme/blob/1.31.1/openstackdocstheme/ext.py#L301

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
Review: https://review.opendev.org/682681

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