Readthedocs documentation is not displayed properly

[gubaidulinvadim]

@TeresiaOlsson @simoneliuzzo I believe there's an issue / missing setting for API Reference documentation. For example, for combined function magnet documentation I was checking the latest now displays example configuration snippet and noticed that there's no separation between Arguments and Methods of a class. Also, there's a doc for init method "Initialises blablabla" but the method itself is not displayed.

Image 1: stable docs

Image 2: latest docs (with config snippet addition)

[TeresiaOlsson]

I see the init problem but what do you mean by "no separation between Arguments and Methods"?

[gubaidulinvadim]

There's no "section" saying methods.

[TeresiaOlsson]

Hmm... Should there be? I tried to look in the pyAT documentation to understand how it should look like when I find the right option but I didn't see a heading for methods there either. Methods are just listed after the parameters?

But what looks very weird to me is that the configuration section has ended up in the middle of the methods?

[gubaidulinvadim]

There's no issue like it. THis is the docstring, Method are listed in the class docstring but readthedocs will list each method's docstring after it. The problem is that it does not seprate each individual method docstring from class docstrings. I'm sure there's an option to do it.

"""
Combined function magnet made up of several virtual single-function magnets.

This class represents a magnet whose effect is described by multiple multipole
components, such as a corrector, quadrupole, sextupole, or octupole family.
Each entry in ``mapping`` creates a virtual magnet backed by the same
underlying magnet model, and the virtual magnets are exposed as individual
elements while still belonging to the same combined-function object.

Parameters
----------
name : str
    Name of the combined-function magnet.
mapping : list[list[str]]
    List of ``[multipole, magnet_name]`` pairs. The first entry selects the
    virtual magnet type, and the second entry gives the name of the virtual
    magnet.
model : MagnetModel | None, optional
    Magnet model used to convert strengths to hardware values and vice versa.
description : str | None, optional
    Human-readable description of the magnet.
peer : object, optional
    Control-system or simulator peer used when attaching the magnet.

Attributes
----------
strengths
    Gives access to the strengths of this combined function magnet in physics unit
hardwares
    Gives access to the strengths of this combined function magnet in hardware unit when possible

Methods
-------
get_model_name()
    Returns the model name of this magnet
nb_multipole()
    Return the number of configured multipole components.
attach(peer, strengths, hardwares)
    Attach the combined-function magnet and its virtual components.
set_energy(E)
    Set beam energy for magnetic-strength conversion.

Raises
------
PyAMLException
    If the mapping is invalid, if an unsupported multipole is requested, or
    if the model does not provide the required multipole information.

Configuration
-------------
The model can be defined inline or in a separate file. See
:mod:`pyaml.magnet.model` and its subclasses for model configuration.

.. code-block:: yaml

    - type: pyaml.magnet.cfm_magnet
      name: COMBINED_FUNCTION_MAGNET_NAME
      mapping:
        - [B2, SEXTUPOLE_NAME]
        - [B0, HORIZONTAL_CORRECTOR_NAME]
        - [A0, VERTICAL_CORRECTOR_NAME]
      model: path/to/combined_function_magnet_model.yaml
"""

[TeresiaOlsson]

I'm also quite sure. There was many options to turn on and I only put some of them. I will do some trial and error.

[TeresiaOlsson]

I have figured out the problem with the __init__. It's because we currently have autoclass_content = "both".

But the question is what we want? These are the available options:

:class-doc-from: (class, init, or both)

    Select which docstring will be used for the main body of the directive. This overrides the global value of [autoclass_content](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content). The possible values are:

        class: Only use the class’s docstring. The __init__() method can be separately documented using the :members: option or [automethod](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-automethod).

        init: Only use the docstring of the __init__() method.

        both: Use both, appending the docstring of the __init__() method to the class’s docstring.

    If the __init__() method doesn’t exist or has a blank docstring, autodoc will attempt to use the __new__() method’s docstring, if it exists and is not blank.

Feels to me like we should go for class, put all parameters in the class and ignore the docstring of the __init__? I have made PR #450 so you can see how the class option would look.

Still working on the method part of the issue.

[TeresiaOlsson]

For the attributes and methods I would actually suggest to remove it from the docstrings. We currently have this:

autodoc_default_options = {"members": True, "show-inheritance": True, "member-order": "groupwise"}

This is why autodoc adds the methods and attributes itself and they appear twice on the page. Then the class docstring is for class level explanation, constructor parameters and configuration, and the information for the attributes and methods are taken from their separate docstrings. I also made a PR #451 to show how that would look.