You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Is your feature request related to a problem? Please describe.
We use portray for docs right now to combine mkdocs (written) and pdocs (code generated) documentation. However, portray and pdocs don't seem to be actively maintained (same author) and have a few issues:
pdocs was originally forked from pdoc for not being maintained (reverse is true now) and missing .md output (since added)
pdocs doesn't include class comments (likely something we could fix, but work 🤷) and shows all inherited methods inline (which is annoying for pydantic model subclasses... ie: everything)
pdocs breaks on generics (eg: list[int]) requiring a fork (since PR likely won't be merged)
Describe the solution you'd like
The code docstrings aren't the most important to document (nor in the best shape), so might be fine to scrap portray+pdocs and only use mkdocs for hand crafted documentation.
When we get around to code docs, pdoc worked a bit better (hiding inherited methods, showed class docstrings, etc) but doesn't include submodules when using __all__ (unless you explicitly add them to __all__, which won't work for the ones we intend to be dynamically imported). It's possible we could change the template or similar, but can punt.
Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered:
Additional context
Add any other context or screenshots about the feature request here:
The text was updated successfully, but these errors were encountered:
(unless you explicitly add them to all, which won't work for the ones we intend to be dynamically imported)
I don't know what exactly your setup is, but if you dynamically modify __all__ that would be picked up by pdoc as well.
Template changes do not work right now as mod.submodules already considers __all__, but if you have a strong interest in that I'd be happy to take a closer look and see if we could change that. :)
Is your feature request related to a problem? Please describe.
We use
portray
for docs right now to combinemkdocs
(written) andpdocs
(code generated) documentation. However,portray
andpdocs
don't seem to be actively maintained (same author) and have a few issues:portray
seems to have a few config edge cases (eg: can't get syntax highlighting, the API reference doc links are dead, etc)pdocs
was originally forked frompdoc
for not being maintained (reverse is true now) and missing .md output (since added)pdocs
doesn't include class comments (likely something we could fix, but work 🤷) and shows all inherited methods inline (which is annoying for pydantic model subclasses... ie: everything)pdocs
breaks on generics (eg:list[int]
) requiring a fork (since PR likely won't be merged)Describe the solution you'd like
The code docstrings aren't the most important to document (nor in the best shape), so might be fine to scrap
portray
+pdocs
and only usemkdocs
for hand crafted documentation.When we get around to code docs,
pdoc
worked a bit better (hiding inherited methods, showed class docstrings, etc) but doesn't include submodules when using__all__
(unless you explicitly add them to__all__
, which won't work for the ones we intend to be dynamically imported). It's possible we could change the template or similar, but can punt.Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered:
Additional context
Add any other context or screenshots about the feature request here:
The text was updated successfully, but these errors were encountered: