PySCeS/pysces

Update documentation

Closed this issue · 8 comments

bgoli commented

Install, readme docs need to be refreshed.

jmrohwer commented

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 commented

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 commented

@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 commented

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 commented

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). ☹️

So, two options:

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 commented

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 commented

Okay, RTD build is finally working with git submodule 😁
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.)