Doc versioning mechanism

The versioning mechanism of the CMake docs is outstanding. I’d like to copy it in a project of mine. I cannot find the sources though, at least not by grepping for “This documents an old version of”
or “Click here to see the latest release” or “select a version from the drop-down menu above”

Is the versioning mechanism part of the CMake sources? Or does it come with a Sphinx module? Is it open source at all?

@brad.king

We configure sphinx with a custom template directory here. That directory contains a custom layout template, which has special version switch code activated by passing -A versionswitch=1 when running sphinx. The version switch code loads version_switch.js, which we publish on the web host here.

The addition of the “This documents an old version of” and “Click here to see the latest release” is done by internal infrastructure we use to prepare the documentation for publication on cmake.org. Basically it updates that same layout.html template:

{%- block relbar1 %}
{{ super() }}
{% if outdated is defined %}
    <div class="outdated">
      This documents an old version of CMake.
      <a href="https://cmake.org/cmake/help/latest/{{ pagename }}.html">
        Click here to see the latest release.
      </a>
      <span class="version_switch_note"></span>
    </div>
{% endif %}
{% endblock %}

Then all the versions except the latest are built with the sphinx -A outdated=1 flag.

That’s very helpful. Many thanks, Brad.

The “internal infrastructure” you mention is just a few scripts to run Sphinx and deploy? Hence nothing I need to worry about before deciding on whether to take the CMake docs as template for my own project?

Yes, the internal infrastructure just makes a few tweaks for publication on cmake.org. It’s nothing heavy. My post above links everything you should need for the version scheme.