Write documentation about multidoc

[FilippoOggionni]

Tasks:

• move content from docstrings README
• restructure existing page about multidoc
• move content from API system README

[FilippoOggionni]

Pages to be reviewed:

1. how to write docstrings (link)
2. yaml templates (link)

Note 1: the second page is only referenced at the end of the first one, but it is not included in any toctree. I think it is fine, because it is simply a template (I am not even sure if it is useful to have it), but I'd be happy to hear your opinion on this page 😃

Note 2: the first page is quite dense of information, let me know if you come up with a smarter way to divide it over multiple pages (in case you think it is needed).

Note 3: most of the content of page 1 was taken from this README. I think I will remove most of the README and just leave a link to the online page. Is this okay?

[FilippoOggionni]

Tagging - as usual - @DominicDirkx @gaffarelj @geoffreygarrett for review (don't hate me 😆)

[gaffarelj]

Great job! 🙂
I like that you used lots of examples where you could. It makes the knowledge of this page a lot easier to "absorb" to me.

Once again, I made some small edits directly with 0489d3d.

It could be good to add, at the beginning of the page, that it is recommended to be familiar with the content of the page about Exposing C++ to Python before trying to dig into exposing docstrings.

Indeed, the "how to write docstrings" page is quite dense, but I think that's okay. It should serve as a reference, and not as something that people will read for leasure, so I'm personnaly okay with it staying like this.

Nothing to say about the YAML templates. Things are clear and I like that it's going to the point directly.

Some small other comments:

Classes, on the other hand, are documented in a more minimalistic manner...

I think that this entire paragraph is quite important, but very abstract. Giving a concrete example of a class, and one of its factory function, could help make things more concrete.

short_description of the constructor method will be given by the string "Constructor"

This sentence is not very descriptive to me, could you detail it just a tad more (nothing too overkill)?

[FilippoOggionni]

Thanks for proofreading and for making the modifications 🙏
Were you familiar with the content? Because if you were not yet you found it clear enough, that's a good sign!

I will address your remarks below:

It could be good to add, at the beginning of the page, that it is recommended to be familiar with the content of the page about Exposing C++ to Python before trying to dig into exposing docstrings.

Will do that!

Indeed, the "how to write docstrings" page is quite dense, but I think that's okay.

I agree, I also had the same impression. We could also find a way to split it though, let's see what the others say!

Giving a concrete example of a class, and one of its factory function, could help make things more concrete

Will do this as well 😃

This sentence is not very descriptive to me, could you detail it just a tad more (nothing too overkill)?

Yes, I will explain it. It simply means the following in the yaml:

- short_description: "Constructor."

Nothing else!

[FilippoOggionni]

Changes have been implemented through 934a94b (and published on the website at latest).

[gaffarelj]

Were you familiar with the content? Because if you were not yet you found it clear enough, that's a good sign!

I was already familiar with it, yes. But I think that it would be clear for someone unfamiliar too (though it would require focussing a little bit more I guess).

Changes have been implemented through 934a94b (and published on the website at latest).

Great, thanks! Especially, the examples you just added really help for the global clarity imo.

[DominicDirkx]

Great work on this, I only have a few points:

• We decided to not have any overloads in tudatpy (?), so this entry can be removed from the page
• I think it would be good to have this page: https://tudat-developer.readthedocs.io/en/latest/primer/docs/docstring_templates.html incorporated into: https://tudat-developer.readthedocs.io/en/latest/primer/docs/docstrings.html#how-to-write-docstrings. The YAML templates tell you what you need to do for the thing you spend the most time on when writing the docstrings. As such, I think it deserves to be on the main page.
• It should be described that the C++ API docs are currently not available (locally nor online)