Make Python program TutorialSteps public

[mhdirkse]

This manual uses custom Python code that mainly resides in folder TutorialSteps. This Python program may be useful for other technical writers. We can move TutorialSteps to a separate project and advertise it.

Here is some background information. The manual explains source code, in our case mainly Frank configurations. It is not wise to write out the source code in the restructured text files. If you want to test such code, you have to copy it to files that can be processed by the interpreter (in our case the Frank!Framework). This approach is tedious and error prone.

It is better to develop the program that is explained in separate files, such that they can be executed directly. For Frank configurations for example, you make a directory containing subdirectories classes, configurations and tests. Such a directory structure can be executed with the Frank!Runner, allowing it to be tested. Then the restructured text files have include directives to reference the files. This way, you are sure that you explain code that works.

This approach has a drawback. You cannot easily take the reader by the hand and develop a source code file step by step. As an example, consider the page https://frank-manual.readthedocs.io/en/latest/gettingStarted/horizonsValidateBooking.html and the way that file Configuration.xml is extended step-by-step. To write such text, you need different snapshots of the code being explained. Each snapshot lives in a directory structure that allows it to be executed. TutorialSteps allows a technical writer to maintain a series of these snapshots.

Each snapshot has a file meta.yml, a YAML file that shows how this snapshot differs from the previous snapshot. If you have to update the files being explained, you typically have to apply the same changes to many snapshots. TutorialSteps detects it when you make errors, because you have introduced differences that are not according to the meta.yml files. In meta.yml, all files being updated in a snapshot are listed. Each file can be added, removed or changed. A changed file can be changed in multiple places. Each of these places is defined in meta.yml with the number of old lines and the number of new lines.

As a second feature, TutorialSteps helps the technical writer to highlight changes. For each changed file, TutorialSteps can generate snippets, which are defined in the meta.yml files. Snippets are text files that have restructured text directives and they present the source code modifications with the right highlighting. Snippets can be referenced with include directives in the main restructured text document.

Here is an example. In page https://frank-manual.readthedocs.io/en/latest/gettingStarted/horizonsValidateBooking.html, file Configuration.xml is given an <Adapter> tag. This looks as shown below:

The main restructured text file has the following contents:

#. Extend ``Configuration.xml`` as shown below:

   .. include:: ../snippets/NewHorizons/v420/snippetAddAdapterAndReceiver.txt

The adapter starts with a ``<Receiver>`` that contains an ``<ApiListener>``. ...

File snippets/NewHorizons/v420/snippetAddAdapterAndReceiver.txt has been generated by TutorialSteps. It reads:

.. code-block:: xml
   :emphasize-lines: 4, 5, 6, 7, 8, 9, 10, 11

   <Configuration
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="../FrankConfig.xsd">
     <Adapter name="IngestBooking">
       <Receiver name="input">
         <ApiListener
             name="inputListener"
             uriPattern="booking"
             method="POST"/>
       </Receiver>
     </Adapter>
   </Configuration>