No version shown

[Andreas Jaeger]

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?

[Stephen Finucane (stephenfinucane)]

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.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/682681

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/682681
Committed: https://git.openstack.org/cgit/openstack/openstackdocstheme/commit/?id=2b2e4e50b6b18fb748bec68b8c40aac56cec3f5a
Submitter: Zuul
Branch: master

commit 2b2e4e50b6b18fb748bec68b8c40aac56cec3f5a
Author: Stephen Finucane <email address hidden>
Date: Tue Sep 17 15:53:50 2019 +0100

    Add 'openstackdocs_auto_version' config option, path checking

    Rather than relying on magic values to determine whether we should
    attempt to auto-version documentation, start checking the paths for
    commonly unversioned source doc paths and add an explicit knob to turn
    this on or off.

    Change-Id: Iecc3fa6f20f1aa92fcffe2b8adb0cd0da1aa17e4
    Signed-off-by: Stephen Finucane <email address hidden>
    Closes-Bug: #1843976