wradlib / wradlib-docs Goto Github PK

The docs are rendered at readthedocs. The correct tag setup need to be created there. For rendering the docs wradlib is installed from the strip1.0.0-branch at the moment.

After switching branches in wradlib (strip1.0.0 -> master) wradlib need to be installed from master branch. In normal operation nothing is changed and latest will be created.

If we have a wradlib tagged release, we want to create dedicated tagged docs using the rendered wradlib-notebooks from the named render branch (eg. 1.0.0). This can be done by creating a tagged release here too (same as wradlib-version).

If readthedocs runs for a tagged release, the correct wradlib-tag gets installed and the correct rendered wradlib-notebooks branch is fetched.

Proposal:

• wradlib release tag: 1.0.0 (considering semver)
• wradlib-notebooks branch: 1.0.0
• wradlib-docs release tag: 1.0.0 (considering semver).

Following this proposal we just have to create a tagged release and the correct wradlib-release and the correct wradlib-notebooks branch will be installed to create the final docs.

Using this scheme, this can be reproduced any time.

The documentation has aged a bit. Some sections could be removed and some sections need update.

• Anaconda/Miniconda/Miniforge
• Bleeding edge code available on testpypi
• Installing via pip
• Dependencies / optional dependencies
• Jupyter HowTo notebook
• Bibliography

Currently we have hyperlinks in the notebooks pointing to the latest compiled wradlib documentation. For the notebooks (in wradlib-notebooks) this is probably the best solution always pointing to the latest available compiled docs.

For the docs itself it is somewhat counterintuitive if you link from the stable version to latest. The suggestion would be to identify these links (they all begin with https://docs.wradlib.org/en/latest/) and correct them to the needed version. This can be done within conf.py where the correct version is already identified.

Thoughts?

Since conda 4.4.0 (released december 2017) the activation process has been reworked. This should be reflected in the docs.

As we do not need to execute wradlib code (besides install stuff), we are mocking out those dependencies. Unfortunately the creation of the conda env consumes quite some time. My suggestion would be to step back to a pip only solution and relying on some packages from the rtd install. This speeds up the build process significantly.

• in organizations
• in projects
• in papers etc.
• etc.