Update documentation

[bgoli]

Install, readme docs need to be refreshed.

[jmrohwer]

What build/deployment system are you using for the docs currently? I see it is hosted by pythonhosted. What is the workflow? Do you build it locally and then upload the HTML to the server?

For PyscesToolbox and NMRPy I use readthedocs (RTD). This is cool because if properly set up, it will automatically build a new version of the docs for every release. In those projects, however, the documentation is part of the same repo, not in a separate repo as for pysces. However, I guess it could be achieved either by moving the pysces-documentation folder into the main pysces repo, or by doing parallel releases on https://github.com/PySCeS/pysces-documentation and https://github.com/PySCeS/pysces. But there may already be another CI workflow in place that I'm not aware of.

If we want to go the RTD route I'd be happy to look into this as I've sorted it out for 2 other projects.

[bgoli]

I was primarily thinking about the markdown docs that are part of the source but it would be good to update these as well. As far as I remember I just built it with sphinx and uploaded it manually. If you would like to move it somewhere else please go for it. I'm not sure hot RTD works but would pulling the docs in as a git submodule work? Then you don't have to include them in your local source if you don't want them.

[jmrohwer]

@bgoli As a first step I have managed to build the docs on my own machine without error. Before moving on to the RTD deployment I'd like to get your input on the sphinx theme to use. I have compiled 3 themes, alabaster (the current one), pyramid (slightly more modern IMO), and sphinx_rtd_theme (specifically for RTD). I have not tried compiling other themes for RTD, but what I like about the sphinx_rtd_theme is that it has its menu in a different frame, so it is always visible, and moreover has autocollapsible subsections. Would you be okay if we go with this theme? (This merely alters the look and feel).

You can preview them all here: http://glue.jjj.sun.ac.za/~jr/alabaster/ http://glue.jjj.sun.ac.za/~jr/pyramid/ http://glue.jjj.sun.ac.za/~jr/sphinx_rtd_theme/

[bgoli]

Excellent, 👍 for the RTD theme.

et me know if I should pull the documentation into the pysces source as a submodule ... if that will work with RTD?

[jmrohwer]

I already pulled the docs as a submodule, if you do a git pull on your side it should refresh. However, there is another snag. Turns out https://pysces.readthedocs.io/en/latest/ is already taken, refers to some fluid dynamics software also called pysces (https://github.com/cwrowley/pysces). :frowning_face:

So, two options:

• use another name on RTD, e.g. http://pyscesdocs.readthedocs.io
• stick with current hosting and just do manual uploads

I am 50/50 on this one. We don't change the documentation that often so the uploads should not be that onerous. It's a tradeoff, but with the current hosting of the docs, the URL is also not that clear about it being a documentation site. What do you think? If we stick with pythonhosted, you'd have to grant me access for doing the uploads.

[bgoli]

Thanks, I'll do a submodule init/update. This is a weird situation but my slight preference would be to go with RTD using a different name - pyscesdocs works for me.

[jmrohwer]

Okay, RTD build is finally working with git submodule :grin: https://pyscesdocs.readthedocs.io/en/latest/

Will now update the most obvious outdated stuff in the documentation for the 1.0 release (e.g. references to Python 2, etc.)

[jmrohwer]

Completed in 7664973 and https://github.com/PySCeS/pysces-documentation/commit/70f0a02b424e76ddad94c2841e0fb88b00b26146