Feature request: Improved documentation

[jspaezp]

I think it would be great to have better docs in a couple of instances.

1. Examples of the supported documentation styles
2. Examples of the changes implied by the configuration arguments.
3. Improve the description of the arguments that shows up with --help to make clear what styles it applies to.
4. Make clear what it entails to change the --style argument or have several, whether it is going to convert the docstrings to that style (example??). And when having multiple styles, whether the expectation should be that it will allow sections that have each style or can each individual docstring have only one?

I think it should be done in a way that it is auto-generated or tested. We could even add some of the formatting tests to the documentation. This would entail some changes in the making/rendering of the documentation.

LMK what you think, I think that if we agree on what the correct approach will be I will be happy to help adding those.
Best!

[DanielNoord]

Thanks for the report! This is indeed a bit lacking currently.

1. Examples of the supported documentation styles

I like this idea. Preferably I would add some links to the style in the README and then have a separate page like the Usage page with some actual examples. Otherwise the README will be too cluttered.

2. Examples of the changes implied by the configuration arguments.

Yes!! Although we should probably tackle this in a separate PR as this will probably require some iterations to get it looking good and having it auto-generated.

3. Improve the description of the arguments that shows up with --help to make clear what styles it applies to.

👍

4. Make clear what it entails to change the --style argument or have several, whether it is going to convert the docstrings to that style (example??). And when having multiple styles, whether the expectation should be that it will allow sections that have each style or can each individual docstring have only one?

👍 I think there is currently not that much overlap and the addition of styles is quite recent but this can definitely be improved!

LMK what you think, I think that if we agree on what the correct approach will be I will be happy to help adding those. Best!

Sounds wonderful! As always, let me know if there is anything I can help you with. I think a PR for each separate point makes the most sense review-wise.

[jspaezp]

#169

It would be a good idea to solve this before documenting ...