Updated Docs, New default for python module

I'm starting this merge now since there are already quite a few changes and we can discuss (and potentially fix) them here before merging.

Main changes:

• Added Documentation (using sphinx and readthedocs theme)
• Added CI scripts (thanks @bgutierrez-garcia !)
• updated/extended the python interface

Documentation

The documentation source is located in ./docs. It is compiled with sphinx.

• the pages are *.rst files (restructured text)
• the main index is in index.rst, and there are 3 subfolders executables/, python/, cpp/ containing the specific parts of the code
• configuration is in conf.py, but that should not be needed to be edited in the future

A preview of the compiled documentation from my fork can be found on the hep server.

Note: I moved some documentation that was previously in the README.md file to the docs, with references to the documentation in the README file.

Python Docs

The python part of the docs is partially auto-generated from the doc-strings in the python module (see e.g. References. The rest of it is more in a tutorial style with links to the references.

The Python class-interface currently doesn't have proper documentation. But it also shouldn't be used in my opinion.

C++ Docs

The C++ docs are split in 2 parts:

• how to add GenericIO as a dependency using CMake, which should make it very easy to create new libraries and executables that use GenericIO, without having to manually copy the GenericIO code into the new source code. In fact, I already used it for the monofonIC initial condition generator.
• how to use the gio::GenericIO class. This part is currently missing as I'm lacking the motivation to write this documentation...

Executables

I listed all the executables and added the usage print as well as options they take. It could use some more details I think, but I'm not using any of these and therefore probably am the wrong person to extend the docs.

I also listed all the environmental variables that are being read by GenericIO, including BLOSC variables that will impact the compression. Since I have no idea what most of these do, that part of the documentation currently just contains the variables without any description.

CI scripts

Ben helped me getting a gitlab-runner based on docker working (on one of the HEP servers). The configuration is located in ./.gitlab-ci.yml. Whenever something is pushed (currently to all branches, we should probably limit it to main/master), the following tasks are executed:

• compilation using the Makefile
• compilation using CMake
• building the python library
• building the docs
• deploying the docs to the webserver

If any of these tasks are failing, the subsequent tasks won't be executed and if you subscribe to alerts, you will get an email notification. If I remember correctly, the deployment of the docs happens in 2 stages, with the gitlab-runner copying it to some temporary directory and a cronjob checking and updating the www folder on the webserver on a regular interval. Ben is the boss.

Updates to the Python interfaces

I deprecated the simple ("old") interface by moving

• python -> legacy_python
• new_python -> python

I also added docstrings to the most used functions (they will show up in e.g. jupyter) and I added some parameters that were previously not passed through the python interface (e.g. eff_rank) and static functions (e.g. setNaturalDefaultPartition).

I also added a pyproject.toml file to comply with the latest python best-practices. It should help with error messages if CMake is not installed / not in the correct version, and it potentially can even install CMake. In the future, we may be able to upload GenericIO to pypi, so that users can simply run pip install pygio without cloning/updating/... the git repo.

Final words

I hope this is useful, especially as more students and external collaborators will be using HACC data. A final note: Nothing in the C++ library has changed, all should exactly work as before

I currently marked it as "Draft", we can remove that once everyone is happy with the changes.