The Best Practice to Contribute to the Documentation

[Hanbing59]

Hello the Dev team of GROOPS,

I have just started with your amazing software by reading the file ./docs/documentation.pdf. It is very helpful and well organized with enough details. I would like to make it better if I may.

I am wondering about how should I start that (Let's say, begin with some typo corrections):

1. After a brief investigation, it seems that, except for some short chapters like the general information, fundamentals and cookbook, most documentations are generated automatically and then the whole documentation is obtained by 'gluing' different chapters together (about the logic if I misunderstood please correct me). While for the short chapters,I can directly modified the source files (e.g., xxx.tex, not the xxx.auto.tex I guess), how should I edit the parts that are generated automatically by groops if I find necessary?
2. There seems to have two versions of documentations: html and latex. Modifications on the LaTeX files seem straightforward. But how about with the html files? Should I also just modify the files directly, and edit the same content twice (like for a typo, one for latex and one html files)?

I am sure that I haven't get the full philosophy behind it. But I'd like to start this process as early as possible. Thanks in advance for your responses!

Best regards,
Hanbing

[tmayerguerr]

Dear Hanbing,

Thank you very much for your kind words. Any assistance in improving the documentation is most welcome.

Most of the latex documentation is located directly at the beginning of the respective source code header .h files (DOCSTRING). This makes it easier to keep the documentation up to date.

Take a look at these directories:

• source/programs
• source/classes
• sources/files: file formats

The following command generates automatically the .auto.tex and .html files (Don't forget to compile after changes)

  groops --doc <pathToGroops>/docs/

The tables are generated from the readConfig() functions directly at the beginning of the actual code.

Best regards
Torsten

[Hanbing59]

Hi Torsten,

thanks for your quick response and detailed instructions.

Just to be sure:

1. except for some short or general documentation, most of the doc are located aside the source codes. So just edit there and re-build (or compile) the whole software package and run the command groops --doc <pathToGroops>/docs/ to get the updated full documentation.

2. No need to do any editing for the html version of documentation, as the command groops --doc <pathToGroops>/docs/ would generate both of the LaTex pdf and html documents.

Do I understand the whole picture correctly?

Best regards,
Hanbing

[tmayerguerr]

Absolutely right. You just need to create the PDF document yourself afterwards with something like: pdflatex documentation.tex.
Best regards
Torsten

[Hanbing59]

Many thanks for your confirmation, Torsten!

[Hanbing59]

Hi @tmayerguerr,

as I start to use GROOPS heavily and read the documentation as well as the source code deeply, I find that, many detailed information about algorithm implementations, their usage, and specifications of some file formats are missing in the documentation, I would like to add to it during my usage. For example, recently I have been working on orbit simulation use the SimulateOrbit program. I found some facts like:

• specifications of the SatelliteModel file seems not enough, e.g., what different types within the surface or modul element mean. Those info would be helpful for users to create their own satellitemodel file manually
• in the OrbitPropagator, users may be curios about the specific orders for some orbit integration algorithms, e.g. what is the most recommended or highest order for Adam-Bashforth-Moulton method should/could be set in GROOPS.

just a few examples. Please do not take those as 'complains'. I know your team have been working on this project using mostly your own spare time and probably would not have too much time and energy for those deep and detailed documentation work. So, I would like to help.

The only question is, should I submit my contribution in a batch style which accumulates a specific amount of modifications or in a smaller and discrete chunk for your review? As I can foresee, it may be hard for me to focus on improving the documentation for a specific module during a specific period, especially at this early stage. It more looks like, I do the supplemental documenting while I am using some programs, reading the documentation and investigating their source codes. So I would say, the second style would be more realistic for me. But I am not sure if this style would add your burden to review.

So, which style of contribution do you prefer more? (Mainly for the documentation part, for the source part, I think, a small but intact and having-been-tested unit contribution is the best style, right?)

Regards,
Hanbing

[tmayerguerr]

Hi Hanbing,

Please do not take those as 'complains'.

I didn't understand it that way either. You have understood the situation correctly. The documentation could be more detailed in many places, and we would be grateful for your help.

I am not an expert in GitHub, and I did not fully understand the intended workflow for pull requests. I often just accept the request directly and then modify the code locally and overwrite the changes with my own commit. If this approach is acceptable to you, I can also handle larger, unstructured requests.

At this point, I would also like to thank you for your contributions and help in the discussions. Unfortunately, I am not always able to answer all questions.

Best regards
Torsten

[Hanbing59]

Hi Torsten,

to be honest I am also not an advanced user of git or github.

But I think, maybe I can just start with some commits and PRs. Let's see how we can improve the workflow.

Regards,
Hanbing