A script is added to the
doc directory to automatically create the documentation pages for the scripts in
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
make_auto_docs.py 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:
Determine whether the information to build the page is enough and its format is clear enough
Add a check for the examples/tutorials that are missing information such that any new file will be written with the specified format
Add the script to the Makefile to run automatically
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 Decided to remove point (4) since it introduces an unnecessary complication.
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.
Work towards DPA task https://gitlab.cern.ch/lhcb-dpa/project/-/issues/204.