Docstring format

[gubaidulinvadim]

As was proposed by Alexis, we need to agree on the format of the docstring (reST, numpy, etc. )

[GamelinAl]

If we want to use sphinx (https://www.sphinx-doc.org/), it should be compatible with it so:

• reStructuredText (https://docutils.sourceforge.io/rst.html#top)
• numpy (https://numpydoc.readthedocs.io/en/latest/format.html)
• google (https://google.github.io/styleguide/pyguide.html)

[TeresiaOlsson]

What is used in pyAT? Maybe it would be easiest to use the same as there for the people who are contributors to both?

[JeanLucPons]

I'm not sure we are fully coherent everywhere in AT concerning the docstring format.
May be @swhite2401 can tell us more.

[gubaidulinvadim]

I don't think pyAT format is one of the standard ones. It's close to numpy one. I'd suggest that for pyAML we just adhere to numpy format for docstrings.

[GamelinAl]

For me, the numpy or google formats have a much better readability than the reST one. So I would advocate for either of these two.
The numpy one is fine for me.

[JeanLucPons]

We have also to think that the docstring format has to be "introspectable" easily in order to provide MetaConfigurator schema with helps.

[TeresiaOlsson]

Ah, okay. What I meant is that a json schema is independent of docstrings and pydantic. It has it's own standard that needs to be followed for existing tools to be able to use it.

A json schema is just a json file which follows some standard structure. It can also be written completely by hand.

But it's more convenient to first write the class and then from the class extract the schema. Pydantic has a function to extract a json schema from a pydantic model and that's what I used. The output is a json file that can be used independently of pydantic. If we don't want to use pydantic I guess we could write our own function to extract a json schema from the pyAML classes. Maybe from the docstrings if we want.

This is the webpage for the json schema standard:

https://json-schema.org/

[TeresiaOlsson]

In the json schema there is a field "description" that is used to show the user the description. But that field doesn't come from the docstring unless you write a function which generates a json schema where the description field is created from the docstrings.

https://json-schema.org/learn/getting-started-step-by-step#add-the-properties-object

This is what I used in pydantic to extract the schema:

https://docs.pydantic.dev/latest/concepts/json_schema/

For there to be a description field in the schema I need to explicitly add it to my pydantic model using Field.

https://docs.pydantic.dev/latest/api/fields/#pydantic.fields.Field

I can also put docstrings for the class but they won't be extracted to the json schema if I use the built-in function in pydantic. They will only show up in the documentation for the class if I generate it with sphinx. That why at least in pydantic the format for docstrings are independent of the json schema.

[TeresiaOlsson]

Or maybe I'm wrong... I have never tested to have a pydantic model without the description in the Field but maybe if that is missing it gets added from the docstrings instead when extracting the json schema. I need to test that.

Here is a discussion about it:

pydantic/pydantic#4281

[JeanLucPons]

Thanks for clarifications.

• Now we have to check that if we use pydantic and put field descriptions in the pydantic field, it has to be able to be docstring compatible.
• The main problem I see with pydantic is the handling of external dynamic modules. As it is done today in my proposal, even if we use pydantic, BaseModel.model_json_schema() will return the models for only 1 class.

[JeanLucPons]

An external UnitConv is a good example of a "middle layer" schema. It is used by internal pymal module and can use one or more pymal internals module. This breaks the global schema.

[GamelinAl]

We decided for the numpy format during the 04/07/2025 maintainers meeting.