Allow documentation to be build without installing and configuring AiiDA #3669
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ltalirz
suggested changes
Dec 14, 2019
There was a problem hiding this comment.
Thanks @sphuber !
To me, this looks great - except for one detail: load_documentation_profile should be part of aiida core.
I don't think it's a good idea to have plugin developers copy this code, which uses AiiDA internals that might change.
docs/source/conf.py
Outdated
|
|
||
| # If we are not on READTHEDOCS load the Sphinx theme manually | ||
| if not os.environ.get('READTHEDOCS', None): | ||
| try: |
There was a problem hiding this comment.
try/except should not be needed here since we have the package in the docs dependencies
|
I would put it in |
sphuber
force-pushed
the
fix_2263_build_docs_dummy_profile
branch
from
dfe458b to
b091030
Compare
Of fair enough, I have moved the function into |
So far, importing aiida would directly create a config file. Such side effects can have problematic consequences e.g. if the default path that AiiDA chooses is not writeable. It also means that you pollute your file system just by importing the package. This PR moves the creation of the config file (if necessary) into the `load_profile` function, which is anyhow called e.g. by the `verdi` command line. The same goes for the configuration of the logger.
To compile the documentation, the code has to be imported which includes the Django database models. Unfortunately, Django will raise here if it has not been configured. Normally this is done through the backend which will load the backend environment for the currently loaded AiiDA profile. Since on readthedocs.org AiiDA is not installed and so there won't be a configuration with a profile to load, the profile management code was monkey patched to provide a dummy profile just for this purpose. Instead of cluttering the main codebase for this one exception, we move the responsibility to the documentation configuration itself. The requirements boil down to the Django settings being called and an AiiDA configuration and profile to be loaded. Since loading a profile with a django backend and loading said backend, the former will be accomplished automatically. This will now also allow building the documentation locally even if the default profile is not using a Django backend because the dummy documentation profile will simply be used. The function `aiida.manage.configuration.load_documentation_profile` performs all the required actions.
sphuber
force-pushed
the
fix_2263_build_docs_dummy_profile
branch
from
b091030 to
f51c231
Compare
ltalirz
approved these changes
Dec 15, 2019
There was a problem hiding this comment.
Thanks @sphuber !
I just restarted the builds - there was an issue on PyPI that should be resolved now https://status.python.org/#past-incidents
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #3390 and fixes #2263
I took PR #3607 as a base. First I reinstated the (unintentionally removed) loading of the Sphinx theme when building the documentation locally. Then I put one commit on top, see commit message for details. Effectively this provides a single function in the docs
conf.pythat fully loads a dummy environment. This is a bit more verbose than the solution proposed by @ltalirz but this removes a lot of code from the main code base that is just there to be able to build the documentation without installation. I feel this does not belong there and should instead be in the documentation configuration. Plugins can simply copy this function and call it to copy the behavior.In addition, this approach now also fixes another issue that required a profile with a django backend to be present locally in order to build the docs. This is no longer necessary and also locally one does not even have to have a profile installed.