Pysteps User reference about pysteps HOT 11 CLOSED

Hi @aperezhortal, thanks for the links. I'm not sure I understand the whole workflow implemented in Wradlib. Why is it necessary to maintain a separate repository for the tutorials?

In the meantime, I've tried out the sphinx-gallery module. I've created a new branch and temporarily hosted the build documentation here. As first example, I've included the cascade decomposition tutorial, you can see the result here.

I've found this module very straightforward, which means that it won't take too much of an effort to convert our existing example scripts into nicely rendered tutorials to be hosted in the User reference.

from pysteps.

@kmuehlbauer thanks for the clarification! The workflow that you describe is very interesting, I think that it worth being considered for future documentation. When I look at it for the first time I missed most of the details that you mentioned.

from pysteps.

This point is very important and should be given somewhat high priority.

We should aim at least at covering all modules with a short tutorial. Most of the code already exists, but we need to find the best way of presenting it.

from pysteps.

The workflow implemented by Wradlib for the user documentation is really interesting.
https://github.com/wradlib/wradlib/wiki/dev.-notebook-workflow

In a nutshell:

1. Maintain a separate repository with the tutorials notebooks
2. Use travis to pull them into the doc dir and create add them to documentation using nbsphinx

from pysteps.

Hi @dnerini, it is not strictly necessary. I think that the objective is to keep the workflow in the notebooks repository separated from the package development repository. This also allows potential users with pySTEPS installed (by pip for example) to clone just the examples and not all the pySTEPS sources (as mentioned in the wradlib documentation). I forgot to mention that the idea was something that we can implement in the future :S

I like the idea of using sphinx-gallery module for the user guide. I'll help you on that branch.

from pysteps.

OK, I now see your point and it is a good one, too. But as you say, this could be implemented in the future and it is probably a good idea to start simple.

Perfect, let's try to implement sphinx-gallery then. The branch I've pushed is probably just a quick and dirty implementation that we probably will need to review.

For example, for some reasons I had to change these few lines in conf.py in order to build the html locally:

from

if 'READTHEDOCS' not in os.environ:
    sys.path.insert(1, os.path.abspath('../../'))

to

sys.path.insert(0, os.path.abspath('../../pysteps/'))

I guess we'll need to set it as you did before merging the branch into master.

Always in conf.py, I've set the output 'gallery_dirs' path of sphinx-gallery in source/auto_examples, but probably a better place would be in _build/auto_examples.

I will probably fix this next. I'm also adding a new tutorial on the noise generation.

from pysteps.

Always in conf.py, I've set the output 'gallery_dirs' path of sphinx-gallery in source/auto_examples, but probably a better place would be in _build/auto_examples.

I have the feeling that this will probably create issues while the documentation is build and the TOC trees are generated. I added this directory to gitignore and modify the rebuild.sh script to remove it like the generated rst files. (commits bc94f04 and 75b791f)

from pysteps.

Yep, you were right, that didn't work. Thanks for the fix!

from pysteps.

@dnerini @aperezhortal Sorry for jumping in. I'm one of the wradlib devs and created that somehow awkward workflow with the notebooks at wradlib.

@aperezhortal Already mentioned on or two of the reasons, but in a nutshell a short summary on the whereabouts:

• dedicated notebook repo (wradlib has quite some notebooks, so we decided to split things up)
  • the notebooks are checked in without rendered output cells (which keeps repo size down)
  • the current master is rendered with each commit to a dedicated branch (devel or 1.3.0)
• dedicated docs repo (this was not an easy decision, but to be honest, only a few people built the docs from sources)
  • in the docs repo within readthedocs we pull in the rendered notebook branch and use nbsphinx to create the final doc
  • that way the notebook creation does not run on readthedocs (blazing fast) and we also can mock out all problematic dependencies
• dedicated code repo (just plain code, might eventually use git submodules to pull in the docs and notebooks repo)

If you have any questions you might just ping me or pull me into some gitter chat.

And besides that, I'm currently exploring pysteps. So I might come back for questions.

from pysteps.

Excuse me for chipping in. I'd love to see a user reference for pysteps, too, and Sphinx-gallery is a really useful tool. In SwirlsPy we found the examples we made (e.g. https://docs.com-swirls.org/auto_examples/qpf_hk.html#sphx-glr-auto-examples-qpf-hk-py) helps our new members and partners getting started quickly.

from pysteps.

Since we first raised this issue, the User reference (and the documentation in general) had improved a lot, with many examples that helps new users to get started quickly.

Commit b7f8bef removes the "Under development" tag form the User reference, thus, closing this issue 🎉🎉🎉

from pysteps.