Automatically generate the docs/api/internal/*.rst files
#290
Comments
tpvasconcelos
added
DOCS
|
hi @tpvasconcelos can i contribute to this issue? maybe you can assign me? thanks! |
|
Hi @imprvhub, thanks for the interest! I've updated the issue description now with some more context. Let me know if you need me to specify anything else. |
|
@imprvhub Ideally this would be integrated in the CI pipeline such that, when a new module is added, the new code won't be merged until this is reflected in the API docs. Maybe this won't be an issue if the automated solution will generate the package tree and module docs on the fly during the documentation build step |
|
Hi @tpvasconcelos, Apologies for the delay—it's been a hectic start to the week! I’m actively working on the solution. The script I’ve created so far generates the .rst files with everything required. However, I’ve run into an issue with modules that have lengthy descriptions, like src/ridgeplot/_ridgeplot.py. I’m currently looking into the best way to address this and aim to have it resolved by tomorrow at the latest. Thanks for your patience, and I’ll keep you updated! 😊 |
This commit adds functionality to automatically generate .rst files for internal API documentation, addressing tpvasconcelos#290. Changes include: - Add script to automatically generate RST files - Support hierarchical module structure - Maintain consistent module descriptions - Add basic tests for core functionality The script detects all internal modules and generates appropriate .rst files with consistent formatting and structure.
|
Hi @tpvasconcelos, I’ve just pushed the PR to automate the generation of the .rst files. I think it’s all working correctly, but if you could give it a try and let me know your thoughts, that’d be great. If there’s anything that can be improved, I’m definitely open to suggestions. Thanks for the chance to contribute to the project! |
|
@imprvhub awesome, thanks a lot for the help here!! I'll take a better look in a few days (sorry!) but already left a few initial comments. |
These files need to be manually kept in sync which is a lot of work and error-prone. Would be better to maintain the project's entire API docs in a more automated way
The ridgeplot API docs include a
Internalssection that should include the entire project's documentationCurrently, each sub-package (e.g.
ridgeplot._color) is documented in a separate page.However, this does not need to be the case. I am okay (and maybe even prefer) if we list all modules in the main API doc page and then a single doc page per module. i.e.,
The way that we currently implement and maintain the current solution is to represent the package structure and modules in RST files, with each RST file containing a
.. automodule:: ridgeplot._color.css_colorsdirective.Note that currently each module contains a short description inside each RST file (e.g., "Continuous colorscale utilities." for
ridgeplot._color.colorscale). This could probably be represented as a module docstring when considering a more automated approach.--
The solution to this problem is not clear to me. Maybe there are already tools out there that solve this nicely (e.g.
sphinx.ext.autodoc,sphinx.ext.autosummary,sphinx_toolbox.more_autodoc, etc...). We could take a look at other prominent projects in the Python open-source space that currently use Sphinx and autodoc for API documentation.The text was updated successfully, but these errors were encountered: