[Biopython] Repositories and URL structure for Biopython documentation?

[Peter Cock]

Hello all,

Historically Biopython's Tutorial and API documentation have lived at
these URLs,

http://biopython.org/DIST/docs/tutorial/Tutorial.html
http://biopython.org/DIST/docs/tutorial/Tutorial.pdf
http://biopython.org/DIST/api

We updated these with each release, originally with static hosting on an
OBF run web-server, nowadays via GitHub pages using this repository:

https://github.com/biopython/DIST/tree/gh-pages/docs

We have a long term goal of moving away from the legacy tool epydoc
to something more modern and maintained for generating the API pages,

https://github.com/biopython/biopython/issues/906

Currently Sphinx and apidoc looks like the best bet. This can now be
automated as part of our regular TravisCI testing, and run locally with
one line:

https://github.com/biopython/biopython/pull/1803

I think this is ready to put up online, and start to gather feeedback
and improvements on the formatting etc (and in the contents of the
docstrings themselves).

I'd like our next release or two to offer both the old epydoc style API
pages, and the new Sphinx API doc pages - which means a new
URL structure.

We could use https://readthedocs.org/ (RTD) and/or GitHub pages. If the
later, a new repository (rather than adding to the DIST repository) seems
best.

Assuming we'd like to take this chance to keep historic version's
documentation online, the version number ought to be part of the URL.
Also, there is some interesting in multiple langauges, so "en" for
English could be in there too - in short we could follow the RTD
conventions and use this kind of URL pattern:

http://biopython.org/docs/en/latest/api/
http://biopython.org/docs/en/1.73/api/

As per the instructions on https://pages.github.com/ for this we'd
need to make a new repository called "docs" under the Biopython
account, much like the existing "DIST" repository.

Note that long term we might move the Tutorial & Cookbook from LaTeX
into reStructuredText, and process that with Sphinx too, which is why
I have put api/ at the end of the URL template.

Can anyone see any problems with this URL scheme and the
plan to create https://github.com/biopython/docs to drive it?

If any of you are already very familiar with fine tuning a Sphinx apidoc
setup (e.g. the theme margins etc), or Read The Docs, your input
would be valuable.

Peter