Skip to content

Help: Add ".. versionadded" directive to every top level .rst document and .cmake module with rst comment

Nikita Nemkin requested to merge nnemkin/cmake:versionadded into master

Motivation

The question of adding "Since 3.X" tags or similar has come up several times in the past (See #19715).

Currently, CMake provides a drop-down documentation version selector. It's useful, but it assumes that sticking to some old documentation set is enough. There are several reasons to prefer the newest documentation set (with version tags).

  • Newer documentation is better formatted and has more detail. Improvements only get merged into the latest version. (Presumably for this reason older docs have a very prominent and difficult to ignore link to the latest version.)

  • A project might want to target a recent CMake on Windows/macOS, but keep Linux build compatible with ancient CMake from popular LTS distros (This is exactly my case). Judging which parts of the build need to be disabled/emulated for an older CMake is difficult without version annotations.

  • It's always useful to see all available features, in case some are worth upgrading for.

Somewhat related issue is that CMake should mark the latest dumentation set as "canonical" for search engines. (So that internet searches don't turn up any random documentation version). It would be appropriate for "canonical" docs to have version info.

Implementation

Sphinx provides three version annotation directives: .. versionadded, .. versionchanged and .. deprecated.

Its easy to automate version tagging (.. versionadded) for top level documents by looking up the first git tag in which the document appears. Given how CMake docs are structured (very nicely), automated tagging is possible for every command, variable, property, module etc.

This PR includes both the script to do automated tagging and the resulting changes. The script could be used repeatedly (as part of release process, for example), but it's not my intention. Ultimately, it's the respoinsibility of documentation writer to provide correct version tags.

Annotating topic lists (for example, cmake-commands(7) page), subcommands (file, string, etc) and other items is a topic for further discussion. I believe some automation is possible there too.

Topic-rename: doc-versionadded

Edited by Brad King

Merge request reports