Documentation review

[jmrohwer]

Hi @bgoli,

I've gone through and edited the entire documentation to bring it up to date with the latest version and also fix some typos, minor errors and inconsistencies. I've also extended the docs in places (e.g. wrote something on the parallel scanner).

I'd appreciate it if you could give it a quick once-over. This could be on Github itself (the RST preview is quite good, only between-file links don't work), or you could pull it on your side. If you need to make changes, GH also allows editing of the RST in place and then committing the changes with a log message.

In terms of editing

There is the following in the source file inputfile_doc.rst (line 87/88) stemming from the original (you can see it here in the original version, just above https://pythonhosted.org/PySCeS/inputfile_doc.html#global-unit-definition)

.. More information on the effect these keywords have on the analysis of a model
.. can be found in the PySCeS Reference Manual. 

I have commented it out for now as you can see, but what is the PySCeS Reference Manual? If it exists, I could link to it, otherwise we should take it out.

N.B. In terms of the way forward

• I have updated the main pysces repo to point to 1d0bfd7 on this repo. Please pull on your side! This is the latest commit before I've started editing on the docs, the ones before that were just to get the RTD build working.
• I need this to build an "old"/previous version of the docs on RTD (RTD can keep old versions of the docs for back reference). I will do this soon.
• To do this I need to add a tag to the main PySCeS repo, I suggest either 0.9.9 or 0.9.8.post2. RTD looks for tags when pulling the source from github. We can't use the existing 0.9.8 since the docs submodule was not in place at that point in the commit history. I guess since 0.9.9 is never formally going to be released, a 0.9.8 based one would be better. This tag is also what the version string in the RTD docs is based on. Since the "post2" is awkward we could also consider 0.9.8a or 0_9_8. This tag (although visible under "tags" in the release timeline, will never be used for a real release. Please let me know what you'd like me to do.
• Once we are done with all the commits for 1.0 on the pysces repo, I'll update the link to point to the latest commit on pysces-documentation, add a tag 1.0 on pysces master, and then RTD will build the new version. I can't do the build prior to that because the link to the submodule needs to be updated.

[bgoli]

Great thanks I'll have look. Regarding the "old doc" tag I would vote for something like 0.9.8a. With respect to new releases, when you make a release GitHub creates a tag automatically from the version number you specify for the release, so you don't need to create it manually ... just point RTD to the release version tag.

I think the Reference Manual never materialised, if anything it should just point to the module docs but just leave it out for now. I'll update the website to include nice links to the RTD documentation (actually pointed a user from Brazil to them this morning).