docs: Automatic Code Documentation #698
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.
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 :)
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 😄
Thanks for trying it out 😄
I ran some tests to check the time of the building process in my local setup:
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:
Signed-off-by: Victor Garcia Reolid <firstname.lastname@example.org>
…date-docs using make) Signed-off-by: Victor Garcia Reolid <email@example.com>
…nternal-modules' into 52-incomplete-documentation-of-internal-modules Signed-off-by: Victor Garcia Reolid <firstname.lastname@example.org>
… comment, as well Signed-off-by: Nicolas Höning <email@example.com>