lmstudio-ai / venvstacks

Virtual environment stacks for Python
https://lmstudio-ai.github.io/venvstacks/
MIT License
1 stars 0 forks source link

Improve the structure of the API docs #33

Open ncoghlan opened 1 week ago

ncoghlan commented 1 week ago

The current API docs are essentially just a sphinx-autogen dump with a bit of manual cleanup to address misfires like including the entire str, Sequence, Mapping, and dict APIs on types that implement those interfaces.

As parts of the API stabilise, their documentation should move away from relying on autosummary and towards regular toctree directives.

Public functions that are missing docstrings should have them added.

The TypedDict metadata is also incorrect (the mapping fields are listed as attributes, which is technically true of the class definition, but not true of the objects that a typechecker will classify as providing that interface).

Finally, while the one-page-per-entity layout is apparently more search-engine friendly, it makes it hard to see how the various interfaces relate to each other, so it's likely worth pushing at least the module level functions and the basic type definitions up to the relevant module pages.