-
Notifications
You must be signed in to change notification settings - Fork 38
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Automatic Code Documentation #698
docs: Automatic Code Documentation #698
Conversation
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool stuff - much better than before, obviously!
First notes:
- This makes the building docs take longer, let's pay attention to that. Is there an easy way to skip this auto-documentation, with a flag or so?
- [possible follow-up issue] We could now fix some modules which have no docstring line in their
__init__.py
. Only utils has one. Same one level deeper. - What is the difference between this and this, information-wise?
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
…e_docs of the makefile command update-docs and update-docs-pdf Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
I've added the flag
You're right! I've simplified the docs to show the description of the objects (classes, functions, attributes and exceptions) in the same page, without any list nor link to single pages. Other than that, we need to decide on the following topics:
Among them, I think some of these could be included in this PR and others might be included later. |
Good improvements! I think it feels weird right now that only "flexmeasures" is listed at first. Maybe it should get its own page, that would be nicer, and maybe it's the quickest way. I would include the short docstrings for the main modules in this PR. Should not be more than ten minutes of work. I'll gladly do it :) |
Thanks!
For this, we can list the main modules when calling autocode.
Okay, thanks. Feel free to do it in this branch or create a new PR to this branch, instead 😄 |
Signed-off-by: Nicolas Höning <nicolas@seita.nl>
Signed-off-by: Nicolas Höning <nicolas@seita.nl>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel the autosummary step is happening regardless of my usage of gen_code_docs
.
At least, I have a length step of "reading sources..."
I tried this, but it didn't seem to work:
if autosummary_generate:
extensions.add("sphinx.ext.autosummary")
extensions.add("sphinx.ext.autodoc.typehints")
Maybe the .. autosummary::
directive will make it happen regardless?
Also, look at this view which should only list the AssetAPI.get
function (endpoint), but seems to list functions of FlaskView
.
Thanks for trying it out 😄
The I ran some tests to check the time of the building process in my local setup:
real 0m12.756s real 0m12.878s
real 0m45.264s real 0m45.483s
real 0m45.039s real 0m46.185s Digging up a little bit, I found that the problem is that autodoc doesn't provide the intermediate RST files, but only the ouputs such as HTML or Latex. For that reason, 159 files need to be "compiled" internally to RST and then to the output format, which slows down the process. Apparently, this is an open Issue in the autodoc repo, but it looks It hasn't received much attention 😢. Also, there is people showing interest in this in a SO post, but the workarounds feel very hacky to me atm. For this reason, I would generate the documentation only when doing changes to main (merge or push) and I don't think it will be a problem in terms of build times given that it runs in 46s in my setup (please, find ReadTheDocs build limits here)
With the new change, I can't see this page being generated. In that page, I see the following: |
I'll have to try again. Which new change do you mean? Happy to see that on RTD we won't have a problem. |
So to get a short run,
That should be off for devs per default and on for RTD I believe. |
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
…date-docs using make) Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
Good idea! Running Otherwise, If they ENV variable |
I think the Makefile should delete the documentation/_autosummary folder, as its existence leads to sphinx working on its content, no matter what |
Can we list the main packages under CODE DOCUMENTATION in the left menu panel of the docs? |
Signed-off-by: Nicolas Höning <nicolas@seita.nl>
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
…nternal-modules' into 52-incomplete-documentation-of-internal-modules Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
Signed-off-by: Nicolas Höning <nicolas@seita.nl>
It did? In only see failed attempts here: https://readthedocs.org/projects/flexmeasures/builds/ |
…hub.com:FlexMeasures/flexmeasures into 52-incomplete-documentation-of-internal-modules
Oh, now it's failing for the secret key haha. I'm adding a random string as well |
Signed-off-by: Nicolas Höning <nicolas@seita.nl>
Oh, I meant locally (with the secret key set) |
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
…nternal-modules' into 52-incomplete-documentation-of-internal-modules
I don't recommend setting those in the conf.py, as then these stick in the devs environment and have to be unset. |
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
As I mentioned earlier, setting these in conf.py might influence the developer environment. |
Signed-off-by: Victor Garcia Reolid <victor@seita.nl>
… comment, as well Signed-off-by: Nicolas Höning <nicolas@seita.nl>
Thanks, it works indeed! The docs building (HTML & PDF) both went from ~40 seconds to ~140 seconds in RTD. |
Great!! Merging into main 🎆 |
Congrats! We did forget the changelog entry that this deserves. Let's just leave the "Still Needs Changelog Entry" label so we catch it during our release process. |
I added the entry, but the internet in the train did not work at that moment, apparently. I'll add it to main now. |
Signed-off-by: Nicolas Höning <nicolas@seita.nl>
Description
This PR makes use of the Sphinx extension
autosummary
to create code documentation straight out of the docstrings!Look & Feel
Testing Steps
Potential Improvements
Deactivate automatic generation on every push as it's very time consuming. By toggling off
autosummary_generate
, for example via a env variable, we can switch off the docs generation.Edit templates.
Closes #52.