GitLab

Description

We want to track changes to the config file parameters over the different versions of the software in the documentation. Sphinx provides three useful directives: versionadded, versionchanged, and deprecated. All take the affected version number as argument and optionally one line of explanation, like so:

.. versionchanged:: 2.2
   Renamed ``ssl`` to ``subsamplingLevel``.

This results in a small rendered message like so:

Changed in version 2.2: Renamed ssl to subsamplingLevel.

Proposal

Support XML tags versionadded, versionchanged, and deprecated in the Python XML reader. XML supports the same tag occuring multiple times in the same level, but our parser does not. Therefore, create a new list for every of these tags. The version should be an attribute of the tag:

<category name="output">
  <parameter name="subsamplingLevel">
     <versionadded version="1.0"> </versionadded>
     <versionchanged version="2.0"> Support ``richards+transport`` mode. </versionchanged>
     <versionchanged version="2.1"> Keywords ``richards`` and ``transport`` may be interchanged. </versionchanged>
  </parameter>
</category>

To do so, extend the attributes of dorie.parscraper.parameter to contain this data. The best thing would probably be a dict, storing the version number as key and the description string as value.

class Parameter:

    def __init__():
        # other attributes ...
        self.versionadded = {}
        # and so on ...

How to test the implementation?

Add a Python unit test: Have the parser read an input XML file and check if all attributes of dorie.parscraper.parameter are set correctly.

Related issues

Meta-issue: #164 (closed)