search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.51k stars 2.12k forks source link

sphinx.ext.autosummary: more customization options. #13003

Open pfebrer opened 1 week ago

pfebrer commented 1 week ago

We are using autosummary to document our package, and we are feeling limited by the customization options currently available. In particular, we are seeing that:

  1. Class templating does not provide enough flexibility for us.
  2. We would like to be able to tweak the display name of the class methods in the tables. For a function module.submodule.func we would like to display it as submodule.func, but the current functionality only allows func or module.submodule.func.

For each of the problems, I would like to propose a new entry point for users to customize the behavior:

  1. Depending on the class, we want to show slightly different documentation. The namespace made available to the template by default however does not allow us to customize the documentation easily inside the template. We have to either design some complex logic inside the jinja template (which looks horrible) or set the global context with the configuration autosummary_context and then query the context for the particular class. It would be very nice if there is a config variable to generate a per-object context. I mean, a function that receives the python object and returns the context that should be made available in the template for that particular object.
  2. A config variable to post-process display names in the Autosummary directive would be very nice.

I think both suggestions I could easily implement them myself and submit a PR, but I would like to understand if this additions would be welcome. It's my first time trying to contribute to sphinx so I don't have a sense for how open to changes things are in the package :)

Thanks!

zerothi commented 1 week ago

To expand on this, the extension `sphinx-autosummary-accesors' is used by other major packages, here pandas and xarray.

The idea would be to allow one to fully customize where the shortening is done:

I.e. right now there is only two options:

~Class.method.attribute
Class.method.attribute

where the first renders only attribute.

However, in the general case it would be nice to do:

(Class.method).attribute
(a.b.c).d.e

to deterministic show only attribute and d.e. The exact invocation can be fine tuned. A single delimiter could also be used:

Class.method|attribute
a.b.c|d.e

or similar.

Quite often would it be useful to document certain things that are tied to a method, or attribute. Especially when dealing with developer documentation where hidden attributes on methods etc. are located.

asmeurer commented 1 day ago

The inability to change a reference from a fully qualified one is also a major issue for us in SymPy. In SymPy, we want users to access most function names from the top-level, like sympy.sin. The fully qualified name like sympy.functions.elementary.trigonometric.sin should be an implementation detail. This is particularly a problem with autosummary since the name becomes part of the URL, and we definitely don't want moving a function around in the source tree to break existing docs URLs. (see https://github.com/sympy/sympy/issues/22105 and https://github.com/sympy/sympy/pull/22589).

There have been a lot of other issues with autosummary (another one I've been following is https://github.com/sphinx-doc/sphinx/issues/7912). I looked into this in more detail a few years ago, and discovered that the biggest issue with autosummary is that it does not actually use the mechanisms of autodoc, but rather reinvents them in a way that isn't fully compatible. My personal opinion is that autosummary should be completely rewritten to handle this better. However, one of the biggest challenges with autosummary and similar systems is that Sphinx has a fundamental design where "documents" have to correspond to "source files". What this means is that it's difficult for something like autosummary, which wants to make a different document for every function, to function in build. Instead, it has to basically write out all the files as a pre-processing step, which limits what it is able to do (see the discussion here https://github.com/Chilipp/autodocsumm/issues/66#issuecomment-986453779).