Building docs errors because INSTALL.rst no longer exists

[LarsKue]

See title. We need to rework the doc building workflow.

[vpratz]

There is a proof of concept to autogenerate docs in PR #250, which also addresses this. As far as I can tell it still needs some work until it is ready, but it might be a good starting point.

[vpratz]

After a long struggle with GitHub actions, we now have multi-version docs on the branch gh-pages-dev. You can check out the branch and run python -m http.server 8080 to view it in your browser. For technical details, please refer to docsrc/README.md.

I have inserted redirects for the HTML pages of the current version of the docs, so we should be able to switch without causing dead links. In principle, the new docs could go live by just switching the branch in the Github pages settings. When do we want this to happen, and for which releases/branches? Do we want to have mutli-version docs for v1? And do we already want to have public docs for the dev branch on bayesflow.org, or rather wait until the official release of v2? Tagging @stefanradev93 @paul-buerkner @LarsKue @marvinschmitt for opinions.

As a note: Building the docs for v2 is quite heavy and takes around 15-20 minutes, total runtime for all versions is about 30 minutes. Do we want to set this up to only run when manually triggered?

[paul-buerkner]

Thank you for making the docs work! This looks really cool!

Our aim is to merge v2 start of next year, so I don't think it makes sense to have a mutli-version for v1. I believe a good time to publish the mutli docs of v2 would be shortly before its merging into main. This way, we could check if everything with the docs works out as we hope before we merge.

I think running the full docs should only be done when manually triggered, say, before a release or after merging a larger PR. Is the slow runtime to be expected?

[vpratz]

Thanks for the feedback!

The slow runtime is due to the way the autosummary is currently configured. We have basically three options to set up the docs:

1. Manually (as before): Is fast, but requires specifying modules by hand
2. Automatically, with automatic generation of documentation for all imports (current setup), using autosummary_imported_members = True. This also analyzes external dependencies (keras, scikit-learn, ...), which makes it slow and somewhat wasteful.
3. For each module, specifiying the publicly exported functions/classes, using Python's __all__ variable in __init__.py. Using autosummary_imported_members = False and autosummary_ignore_module_all = False, this should allow us to make the intended API structure known to autosummary (and the public at large), while (as far as I can tell for now) keeping the process fast.

We cannot simply disable autosummary_imported_members, because we use imports in the modules __init__.py to gather functions and classes that would then go unnoticed and not be included.
Option 2 is the most automated, but slow and does not allow fine-grained control. Option 1 and 3 both require manual work to declare the API structure. If we should go for one of them, I think option 3 would be the more idiomatic way, as we can specify what parts of a module should be public directly in the code using __all__. Maybe this would be something worth doing anyway? @LarsKue, what do you think?

[vpratz]

Is the slow runtime to be expected?

It turned out that the configuration was not optimal yet. I have modified it, and now it runs at reasonable speed (5-8 minutes). With this, we could afford to run it more often if we want. This could also serve as a check if the documentation will still build after a commit/PR.

The main remaining issue is how to exclude private members/modules, which we can discuss in #290. I will close this for now, feel free to reopen or open a new issue if you have ideas/requests for the API docs.