Old version information should be configurable

[Andreas Jaeger]

Have a look at http://developer.openstack.org//api-ref/identity/v2/index.html

The version information here makes no sense, we do not have links to old documents for the api at all. These links should not appear. Can we make them configurable, please?

[Dolph Mathews (dolph)]

Are you referring to the "Other Versions" section on the left column?

[David Stanek (dstanek)]

@Dolph, I would guess yes. Those links are bad and a quick look at oslosphinx shows that it automatically generates those links based on the git tags. There doesn't seem to be any easy way to customize this beyond a custom theme.

Three options as I see it:

  1. Make those links configurable in oslosphinx
  2. Publish the older docs
  3. Create a custom theme based on the default theme

[Andreas Jaeger (jaegerandi)]

Dolph, yes, I'm referring to the "other versions" on the left there.

[David Stanek (dstanek)]

Our generated documentation definitely has broken links.

[Steve Martinelli (stevemar)]

adding ironic since they have the same problem: http://developer.openstack.org/api-ref/baremetal/index.html

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/340508

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/340509

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/340515

[David Stanek (dstanek)]

I've come up with two different ways in oslosphinx to make this configurable. Looking for some feedback on which one to pursue.

https://review.openstack.org/#/c/340508/
https://review.openstack.org/#/c/340509/

[David Stanek (dstanek)]

This bug is not just for api-ref documentation, but affects anything using the oslosphinx theme. I've made a keystone patch for api-ref and developer documentation that depends on the oslosphinx changes.

[OpenStack Infra (hudson-openstack)]

Change abandoned by David Stanek (<email address hidden>) on branch: master
Review: https://review.openstack.org/340508
Reason: Going with https://review.openstack.org/#/c/340509 instead

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/340509
Committed: https://git.openstack.org/cgit/openstack/oslosphinx/commit/?id=3bcdfc6b77212ce802763c4fadea0bed08ca42fe
Submitter: Jenkins
Branch: master

commit 3bcdfc6b77212ce802763c4fadea0bed08ca42fe
Author: David Stanek <email address hidden>
Date: Mon Jul 11 16:49:48 2016 +0000

    Allow "Other Versions" section to be configurable

    Adds a new option that allows the "Other Versions" section to be removed
    if a project isn't interested in showing links to older versions. The
    default value is False which means that it will be hidden.

    Even though the setting is not backward compatible there are enough
    broken documentation links in the OpenStack projects that this should be
    opt-in behavior.

    Change-Id: Ic4b47b19aa9db38557c37aed7722174b7dbdf4a1
    Closes-Bug: #1599260

[Steve Martinelli (stevemar)]

I believe this is a no-op for keystone and ironic now, we'll automatically pick up the new oslosphinx and it'll be fixed, i'm marking them as invalid

[Doug Hellmann (doug-hellmann)]

This issue was fixed in the openstack/oslosphinx 4.7.0 release.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslosphinx 4.7.0 release.

[OpenStack Infra (hudson-openstack)]

Change abandoned by Steve Martinelli (<email address hidden>) on branch: master
Review: https://review.openstack.org/340515
Reason: https://review.openstack.org/#/c/340509 was merged instead

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslosphinx 4.7.0 release.