Check documentation is correct and it renders correctly

[llucax]

What happened?

The generated documentation has several issues that prevents proper navigation or visualization. These issues are not only in the docstrings, sometimes how the code is structured makes the documentation not render properly.

This is a tracking issue to collect all of these problems to be able to fix them, and also to write a guide on how to write proper documentation (and code structure) so it can be rendered properly.

• Improve @property documentation #39
• Nested classes don't get properly linked (we might consider avoiding them if part of the public interface) [example | source] Support cross-refs in attributes signatures / Support stringified types in base classes subscripts mkdocstrings/mkdocstrings#586
• Document enum members (otherwise they are not shown in the docs) [example | source]
• Check if we can use a shorter documentation for simple methods just returning one value, omitting the Returns: section.
• Make sure all types that are returned are exposed publicly (for example FormulaEngine is returned by public methods but it's not exposed publicly, see Add pv optimization tutorial #700 (comment))
• Make public all parameters (TypeVars) of all generic public classes (we used to use _T to make it private so it can't be accidentally imported by other modules, but that means it is hidden from the docs too, which hides important information, like constrains, bound and co/contravariance)
• Add cross-linking for the in_shifting_group option (see Support power requests from shifting actors in the PowerManager #957 (comment)).

What did you expect instead?

The documentation being rendered correctly.

Affected version(s)

No response

Affected part(s)

Documentation (part:docs)

Extra information

No response