Auto document methods?

[tylerflex]

Something to think about regarding the docs

It would be fantastic if we could come up with a way to automatically parse method docstrings and call signatures to create nicely rendering docs without having to do it manually.

    @classmethod
    def dict_from_json(cls, fname: str) -> dict:
        """Load dictionary of the model from a .json file.

        Parameters
        ----------
        fname : str
            Full path to the .json file to load the :class:`Tidy3dBaseModel` from.

        Returns
        -------
        dict
            A dictionary containing the model.

        Example
        -------
        >>> sim_dict = Simulation.dict_from_json(fname='folder/sim.json') # doctest: +SKIP
        """

would become something like

    @classmethod
    def dict_from_json(
        cls,
        fname: str # Full path to the .json file to load the :class:`Tidy3dBaseModel` from.
    ) -> dict: # A dictionary containing the model.
        """Load dictionary of the model from a .json file.

        Example
        -------
        >>> sim_dict = Simulation.dict_from_json(fname='folder/sim.json') # doctest: +SKIP
        """

[daquinteroflex]

Sounds good will have a think on easy development implementation schemes.

Thought just to write a few things I've noted about the API docs implementation.

Currently, we are using sphinx.ext.autodoc and autodoc-pydantic. However, when you look at the generated class docs such as currently in this doc, it doens't actually use the autodoc pydantic generated output template.

I went deep into investigating this. Really it can all be summarised in this issue:

The generated stub pages do not use the standard autosummary templates (e.g. the class template which lists all methods and attributes). As of sphinx version 3.5.4, this is not possible because autosummary does not support custom autodocumenters provided by extensions such as autodoc_pydantic (see sphinx issue 6264). Instead, autodoc_pydantic’s autodocumenters are used to render the object’s documentation in the generated stub pages of autosummary.

When we were generating the _autosummary documentation before, we were generating it in a way that was incompatible with autodoc-pydantic.

This is how it was before:

tidy3d.Simulation
=================

.. currentmodule:: tidy3d

.. autoclass:: Simulation

   .. automethod:: __init__

   .. rubric:: Methods

   .. autosummary::

      ~Simulation.__init__
      ~Simulation.add_ax_labels_lims
      ~Simulation.add_type_field
      ~Simulation.bloch_with_symmetry

This was incompatible with autodoc-pydantic usage. I tried to fix that in a current demo and by fixing autodoc-pydantic by applying a template:

# _templates/module.rst
{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}
   :members:
   :show-inheritance:
   :member-order: bysource

However, we can see by the given output that there is still a problem. I don't fully get why autodoc-pydantic doesn't include non-validation methods which we commonly employ in our API. I need to go through their API throughly as it's not in the docs how to enable this.

Potential solutions in evaluation:

• Can we replace autodoc-pydantic by some custom template that interacts better with _autogenerate?
• Can we improve autodoc-pydantic or find a way to include non-validation methods?

The styling is the easy part. The issue is getting the autogenerated page to have all the meaningful information we want to display.

[daquinteroflex]

Just for update, after a very thorough testing, I've decided to ditch autodoc-pydantic (for now at least, don't know if post >v2 full migration it makes a revival). The reason is simple: I don't think it really is adding that much value right now and I have a strategy to improve the docs in a much more raw form based on the requirements of https://github.com/flexcompute/tidy3d/issues/1197 + others

[tylerflex]

Sounds good. Let's do it.

[daquinteroflex]

Will transfer this issue to the autoflex extension project.