Skip to content

Automatic documentation of DaVinciExamples and DaVinciTutorials

Maurizio Martinelli requested to merge mamartin-dvdocs into master

A script is added to the doc directory to automatically create the documentation pages for the scripts in DaVinciExamples and DaVinciTutorials and show them in the section Examples and Tutorials of the DaVinci documentation site.

The script so far creates the documentation pages based on information added on top of the original python files. The information is formatted in the form of a comment

<minimal description of the python script>

rst_title: <documentation page title>
rst_description: <documentation page description>
rst_running: <script to run the example/tutorial>
rst_yaml: <address of the yaml file relative to the 'doc' folder in DaVinci>

Further sections can be added if needed. The information above is decoded in the function GetPageInfo of and used in the functions WritePage to create the page. The index for DaVinciExamples or DaVinciTutorials and their respective sub-folders is written by the function WriteIndex that is called recursively when a sub-folder is found.

For this mr to be completed there are a few issues to resolve:

  1. Determine whether the information to build the page is enough and its format is clear enough
  2. Add a check for the examples/tutorials that are missing information such that any new file will be written with the specified format
  3. Add the script to the Makefile to run automatically
  4. Add a check in the Makefile to commit all new files created by the script (and remove those that changed? i.e.: file changing name) Removed

For 1 I would like feedback from other people (@erodrigu).

Item 2 was suggested by @pkoppenb during the DPA-WP3 meeting of 18/1/2023.

Item 3 should be easy, since the relevant code is just commented in the Makefile.

For the last point (4) I am planning to write a script that runs a diff after the execution of the script to check all the differences in the doc folder (excluding doc/_build) and apply the relevant commit in the Makefile. In the example from the Functors documentation, only one file needs to be committed, while here there may be many and they may change over time. Decided to remove point (4) since it introduces an unnecessary complication.

Work towards DPA task

Edited by Eduardo Rodrigues

Merge request reports