docs: Automatic Code Documentation

[victorgarcia98]

Description

This PR makes use of the Sphinx extension autosummary to create code documentation straight out of the docstrings!

Look & Feel

Testing Steps

python3 -m venv venv
source venv/bin/activate
make install
make update-docs

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.

[nhoening]

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?

[victorgarcia98]

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?

I've added the flag gen_code_docs which controls if we want to generate the docs or not.

What is the difference between this and this, information-wise?

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:

• Format of the documentation for a (sub)module (order of elements, lists, ...).
• Modules to avoid, for example, the CLI it's pretty much covered in this page and autodoc fails to capture Click commands.
• To have or not have a main page for the code documentation.

Among them, I think some of these could be included in this PR and others might be included later.

[nhoening]

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 :)

[victorgarcia98]

Thanks!

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.

For this, we can list the main modules when calling autocode.

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 :)

Okay, thanks. Feel free to do it in this branch or create a new PR to this branch, instead 😄

[nhoening]

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.

[victorgarcia98]

Thanks for trying it out 😄

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..."

The gen_code_docs actually disables the generation of the file structure, all the RST files containing the documentation for the modules (autosummary). This flag doesn't deactivate the generation of the HTML from the code (i.e autodoc).

I ran some tests to check the time of the building process in my local setup:

1. Benchmark (commenting the autosummary code in index.rst and _autosummary folder deleted):

real 0m12.756s
user 0m14.160s
sys 0m5.360s

real 0m12.878s
user 0m14.142s
sys 0m5.422s

2. Full code docs generation: make update-docs gen_code_docs=True

real 0m45.264s
user 0m46.346s
sys 0m5.641s

real 0m45.483s
user 0m46.203s
sys 0m5.513s

3. Disable autosummary make update-docs gen_code_docs=False

real 0m45.039s
user 0m46.026s
sys 0m5.650s

real 0m46.185s
user 0m47.098s
sys 0m5.693s

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)

Also, look at this view which should only list the AssetAPI.get function (endpoint), but seems to list functions of FlaskView.

With the new change, I can't see this page being generated.

In that page, I see the following:

[nhoening]

With the new change, I can't see this page being generated.

I'll have to try again. Which new change do you mean?

Happy to see that on RTD we won't have a problem.

[nhoening]

So to get a short run, code_gen_docs set to False, we'd need to do this, as well?

commenting the autosummary code in index.rst and _autosummary folder deleted

That should be off for devs per default and on for RTD I believe.

[victorgarcia98]

Good idea!

Running make update-docs or make update-docs-pdf set gen_code_docs to False, by default.

Otherwise, If they ENV variable GEN_CODE_DOCS is not found, the default would be True.

[nhoening]

I think the Makefile should delete the documentation/_autosummary folder, as its existence leads to sphinx working on its content, no matter what gen_code_docs says.

[nhoening]

Can we list the main packages under CODE DOCUMENTATION in the left menu panel of the docs?

[nhoening]

It did? In only see failed attempts here: https://readthedocs.org/projects/flexmeasures/builds/

[victorgarcia98]

Oh, now it's failing for the secret key haha. I'm adding a random string as well

[victorgarcia98]

Oh, I meant locally (with the secret key set)

[nhoening]

I don't recommend setting those in the conf.py, as then these stick in the devs environment and have to be unset.
See how I am adding them in .readthedocs.yaml. However, I also failed with SECRET_KEY. Will go to bed now...

[victorgarcia98]

I've tested just to set the variables SQLALCHEMY_DB_URI and SECRET_KEY in documentation/conf.py and the build succeded. You can see the results here.

Please, let me know if there's any other request from your end. Otherwise, we can merge 😄

[nhoening]

As I mentioned earlier, setting these in conf.py might influence the developer environment.
Aren't you overwriting your FM configuration with dummy values, making it impossible to test real functionality?

[nhoening]

Thanks, it works indeed!

The docs building (HTML & PDF) both went from ~40 seconds to ~140 seconds in RTD.
Seems we can afford it. The overall build time has other overhead, as well.

[victorgarcia98]

Thanks, it works indeed!

The docs building (HTML & PDF) both went from ~40 seconds to ~140 seconds in RTD. Seems we can afford it. The overall build time has other overhead, as well.

Great!! Merging into main 🎆

[Flix6x]

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.

[nhoening]

I added the entry, but the internet in the train did not work at that moment, apparently. I'll add it to main now.