New Functions or Classes

When adding a new method or class to the project, please keep in mind that there are changes necessary, if you add external packages. You have to add them to the docs/source/requirements.txt file to make the actions for the documentation pass.

New Class

Add the new class (with documentation in numpydocs format) to the source code. Then create a directory with the class name in docs/source/classes/ and edit the index.rst file. There, you should add DIRECTORY_NAME/index. Go to the directory for the class and create the index.rst file you have just referenced in the previous index.rst file. There add something similar to the following example for the Oscar class:

.. _oscar:

Oscar
=====

.. currentmodule:: Oscar
.. autoclass:: Oscar

.. automethod:: Oscar.particle_list
.. automethod:: Oscar.particle_objects_list
.. automethod:: Oscar.num_events
.. automethod:: Oscar.num_output_per_event
.. automethod:: Oscar.oscar_format

All the methods that should be visible in the final documentation page should be added with the .. automethod:: command.

New Class Method

Write the documentation for the new function. Then add the method to the Methods section of the raw code documentation (first documentation block in class). The last thing is adding the method to the documentation (last step in the previous section). Check if new third party libraries are imported, if yes, then add them to the docs/source/requirements.txt file.

Free Function

If you add a new function which doesn't deserve its own class and file, then you can add this function in the Utilities.py file, where we collect the free functions of the SPARKX package. Equip the new function with a docstring and add the function in docs/source/utilities/functions/index.rst with the .. autofunction:: Utilities.name_of_the_function command.