Readthedocs documentation is not displayed properly

@TeresiaOlsson

@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)

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

There's no "section" saying methods.

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?

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
"""

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.

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.

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.

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.

I don't like this solution.

It's quite convenient to have attributes and methods in the class docstring. You get the information with just print(Object).
It's good to have online documentation like read the docs, but the true source of documentation is the source code.

For pyAML projet it's even more important, in many control room you don't have internet access on the computer which can control the accelerators.

But the solution to not have docstrings at the function level I think is worse? Then you have to go to the class docstring every time you look at the source code and want to know what a method is doing?

Also why do you want to use print for this and not help? Or you meant help?

I think print should just return something short describing what the values are for the current object and help should return the info in the docstrings. I thought help could already handle combining class, attribute and method docstrings into one but if not we can maybe customize it.

If help is no good I think we can also add a method describe. I have already had to add that on ConfigurationSchema to have some way to return a user-friendly string of what the fields are of a class. But help would be nicer since it's the standard way of doing it so the users might already know it. And for the MML users that's already how you would get the docstrings in matlab.

I meant help sorry ...
I will try to come up with a proposal to solve this.

@TeresiaOlsson

@TeresiaOlsson is there a way to test how the documentation looks in a given branch?

I meant help sorry ...
I will try to come up with a proposal to solve this.

I haven't tested what help returns but I think the ideal solution would be if we could have the docstrings distributed in the source code and still get help to return the nice explanation you want where all the docstrings are put together.

For the sphinx documentation it would work to put everything in the class docstring but then I need to turn off the option to include docstrings from attributes and methods or the same info will be twice. And that worries me a bit because it means that if someone isn't aware of this decision and writes distributed docstrings they will be lost in the docs. So if it's possible to fix in help that feels more robust.

@TeresiaOlsson

@TeresiaOlsson is there a way to test how the documentation looks in a given branch?

Not so good for the project wide documentation (that you have to build locally to see) but for the API documentation on readthedocs you should just need to make a PR (draft should also work) and in the PR readthedocs should appear and provide a link to click on to get the docs for that PR when it has finished building it.

@TeresiaOlsson

@TeresiaOlsson is there a way to test how the documentation looks in a given branch?

Not so good for the project wide documentation (that you have to build locally to see) but for the API documentation on readthedocs you should just need to make a PR (draft should also work) and in the PR readthedocs should appear and provide a link to click on to get the docs for that PR when it has finished building it.

If it doesn't work it would be because I have forgot to turn on PR builds for that specific repository. But that's just a click in the readthedocs settings to turn on.

@TeresiaOlsson

Thanks @TeresiaOlsson , it's clear how to see the documentation in a PR now.
Have a look at the proposed solution in #453

for Sextupole class
New:

Present doc:

For Accelerator class
New:

Present doc:

Looks very nice! I will check the details of how you implemented it in the PR:

Closed with #453

Navigation Menu

Repository navigation

Readthedocs documentation is not displayed properly #447

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Readthedocs documentation is not displayed properly #447

Description

Activity

TeresiaOlsson commented on Sep 18, 2026

gubaidulinvadim commented on Sep 18, 2026

TeresiaOlsson commented on Sep 18, 2026

gubaidulinvadim commented on Sep 18, 2026

TeresiaOlsson commented on Sep 18, 2026

TeresiaOlsson commented on Sep 18, 2026

TeresiaOlsson commented on Sep 18, 2026

GamelinAl commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

GamelinAl commented on Sep 23, 2026

GamelinAl commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

GamelinAl commented on Sep 23, 2026

TeresiaOlsson commented on Sep 23, 2026

GamelinAl commented on Sep 24, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions