Suggested additions to the documentation

[philipcardiff]

Hello!

Thank you for sharing the repository

Related to the review at https://github.com/openjournals/joss-reviews/issues/6200, I have the following commands and suggestions:

• A statement of need: On the main page, it would be useful to more explicitly state what problems the software is designed to solve and who the target audience is. For example, I am still not entirely sure what predictions the tool is actually making and how it should be used.
• Example usage: For the "Basic Example" at https://pyroll.readthedocs.io/en/latest/examples/basic.html, it would be useful if you could briefly explain what this example is doing, i.e. what it is simulating, what are the inputs, what are the outputs. It seems to be a relatively complex process (many passes) for a basic example; I wonder if a demonstration of a more simple example with a more detailed description would be more helpful in teaching new users about using the tool? Alternatively, it would be good if you could give more details about the input file.
• Example usage: At the end of https://pyroll.readthedocs.io/en/latest/examples/basic.html, it would be useful if you could provide instructions on where to learn more about how to use the packages (i.e., which page should I go to next). For example, I see that the definition of a RollPass is explained in https://pyroll.readthedocs.io/en/latest/examples/step_by_step/index.html#using-just-the-core.
• Automated tests: Does the repository contain any test script to check if it was installed correctly? For example, a test script runs a simple problem and compares the answers to reference values.
• Functionality: It would be useful if the documentation summarised the main functionality of the toolbox, that is, what features it has and what it can do.

[ChRen95]

@axtimhaus you want to handle this on your own or shall we share the work load?

[axtimhaus]

I will see to replace the basic example with the notebook from the examples repo, which should fit the needs: https://github.com/pyroll-project/pyroll-examples/blob/main/Basic_Usage_Of_PyRolL.ipynb

The textual parts I will do on my own and afterwards file a pull request.