aesara-devs / aesara

Aesara is a Python library for defining, optimizing, and efficiently evaluating mathematical expressions involving multi-dimensional arrays.
https://aesara.readthedocs.io
Other
1.18k stars 153 forks source link

Automate the enumeration of library objects in the documentation #752

Open brandonwillard opened 2 years ago

brandonwillard commented 2 years ago

Tables for collections defined in code, like the implemented Modes, and Linkers, optimization DBs, available rewrites/canonicalization spec, etc., need to be generated automatically when our documentation is rendered.

In order to implement some of this, we may need to add additional documentation strings to the underlying objects, but that's likely fine in most cases. If need be, we can always use separate annotations that only exist in the documentation code that parses the library objects, but we should really try to put the onus of writing and maintaining this information on the developers who add/change the objects themselves—without requiring the context switching involved in updating .rst documents or documentation-related code.

This work may also serve as a start to our long needed meta information gathering; the kind that will help us systematically analyse and refine the canonicalization and "optimization" processes.

brandonwillard commented 1 year ago

https://github.com/aesara-devs/aeppl/pull/221 provides a working example of how this can be done using custom SpinxDirectives.