Repository: biopython/biopython

Issue:
Version switching on the Sphinx API docs
We now have:

- https://biopython.org/docs/1.74/api/
- https://biopython.org/docs/1.75/api/
- https://biopython.org/docs/1.76/api/
- https://biopython.org/docs/1.77/api/
- ...
- https://biopython.org/docs/dev/api/

The webpage source for these exists here:

https://github.com/biopython/docs

The Sphinx configuration to build them is here:

https://github.com/biopython/biopython/tree/master/Doc/api

Can we add some JavaScript or otherwise like on ReadTheDocs to make it easy to toggle between version from within the browse?

This likely means some changes to our Sphinx configuration (e.g. the common templates), and therefore would require backporting to regenerate the old pages - which would be OK.

This could also resolve #2904.


Discussion:
@peterjc  Hi! 
Have you seen https://github.com/sphinx-contrib/sphinxcontrib-versioning ? It seems as though it could work. 
That sounds worth exploring (GitHub emailed me after your edit, I must have missed your comment back in June - sorry)
https://github.com/biopython/biopython/blob/f95d94573b7f45728cbb66814bfe2cad3e7f0e2e/Doc/api/conf.py#L134-L147

Is this 'active', has it any effect? Where would be the files that are mapped here?

I also found this SO question: https://stackoverflow.com/questions/49331914/enable-versions-in-sidebar-in-sphinx-read-the-docs-theme which may help here.

I guess there is no other way than testing such things locally, am I right? So I would need to install Sphinx and make local copies of the respective repositories/folders?
Yes, doing it locally would be best - but this should work with minimal manual dependency installation:

```
$ git clone git@github.com:biopython/biopython.git
$ cd biopython
$ tox -c .travis-tox.ini -l  # optional
$ tox -c .travis-tox.ini -e api # currently reports lots of warnings 
$ open Doc/api/_build/html/index.html
```

Running locally will not attempt to push the build to the GitHub Pages docs repository - you won't need to touch that until we have something ready to live test. If you want to test online, you could use your personal github pages setup, for example https://peterjc.github.io/ currently has a copy of the main home page.

*Update:* Tox is meant to install biopython (locally) as part of this, and it works on TravisCI. But looking at the logs, you way need to (re)install Biopython too, otherwise it might be looking at any (older) installed version not the local copy. Or maybe I am confusing myself trying to clear some of the excessive section title warnings :shrug:
As an aside, maybe we should rename ``.travis-tox.ini`` to just ``.tox.ini`` (still hidden) or one of the defaults like ``tox.ini`` (clutters the top level file listing slightly).
Making the api docs with Sphinx under Windows
---------------------------------------------------
(for reference, if someone, e.g. me, has similar problems in the future)

System setup: Windows 10, 64 bit, Python 3.7.4, installed with Miniconda, Visual Studio 19 command line tools installed (for compiling C files)

Before starting, I installed `tox` and `Sphinx` (via `conda install ...`)

In my Bopython git environment:
```
$ git checkout -b api_docs
$ tox -c .travis-tox.ini -e api
```

The adventure begins!

Quests (not in chronological order)

- Although Git for Windows operates with a MinGW bash commandline, it does not have the command `make`. Pimp your MinGW with `make` as described here: https://gist.github.com/evanwill/0207876c3243bbb6863e65ec5dc3f058
- Although Git for Windows ... (see above), paths need backslashes as separator, so `travis-tox.ini` must be changed to
  ```
  commands =
    bash -c \'python setup.py install' # don't know how to  > /dev/null\' here
    make -C Doc\api\ html
  ```
- Use `tox` with verbosity, best `-vv`. In my git environment, `tox` tends to crash or hang silently without returning when encountering an error condition. With verbosity on it will display the error messages and returns (yes, that's strange, but really, I spent at least 30 min waiting for `tox` to return and report something).
- Although at the beginning `tox` declares happily that all requirements are meet and everything has been installed, later it (or Sphinx?) complains about missing dependencies. I had to manually install `numpydoc` and `sphinx_rtd_theme`
- `setup.py install` fails with the error that a Visual C compiler is needed. So I did the build separately/manually (install will use the files in the `build` folder)
- Finally everything run through but `tox` exited with an error condition, although everything seems to have worked:
  ```
  build finished with problems, 12 warnings.
  make: *** [Makefile:20: html] Error 1
  make: Leaving directory 'E:/git_32bit/biopython/Doc/api'
  ERROR: InvocationError for command 'E:\git_32bit\mingw32\bin\make.EXE' -C 'Doc\api\' html (exited with code 2)
  api finish: run-test  after 379.18 seconds
  api start: run-test-post
  api finish: run-test-post  after 0.00 seconds
  ___________________________________ summary ___________________________________
  ERROR:   api: commands failed
  ```

- The contents are fetched from the systems's Biopython. My doc html files are labelled as `1.76` and have the corresponding content (e,g., `Bio.Seq.Seq` still having the alphabet), while my git Biopython is 1.79dev.

Now I can start experimenting...



  
 
Ah - I thought I was seeing it build Docs for the installed Biopython rather than the local copy (macOS). Perhaps Sphinx is escaping Tox's environment somehow... but it works on TravisCI. Strange.
We now have version switching for the documentations of Biopython 1.74 to 1.78 (dev version is to come) with the options "Previous|Latest|Develop".

The previous version number is calculated in `conf.py` from the latest version number (version - 1 or version - 2 if dev-version), which is a bit fragile in case we should have version gaps (can this happen?).

Whatever, it seems that there is no easy way to extract the number and names of archived documentations from the biopython/biopython repository; in biopython/docs one could read the directory to list the available documentation versions, but this is not accessible to `conf.py`.

Thus, I'd like to suggest putting a text file to biopython/biopython's `Doc/api` folder which contains a list of the available Sphinx-generated documentation versions. This could be read and automatically updated by `conf.py` and would allow for more flexible version switching (if desired).
 
I'm unclear what the text file listing adds over the directory listing?
How can `conf.py` easily access the directory listing in a different repository?
I was thinking in terms of the deployment script (which would have both repositories). Fair point, in the context of building the docs, we don't have this information.

Resolving patch:
diff --git a/Doc/api/conf.py b/Doc/api/conf.py
--- a/Doc/api/conf.py
+++ b/Doc/api/conf.py
@@ -61,6 +61,25 @@
 # The full version, including alpha/beta/rc tags.
 release = __version__
 
+# Versions for versions.html:
+# (this will break if we have version gaps)
+try:
+    main_version, minor_version, _ = version.split(".")  # e.g. 1.79.dev0
+    dev_version = True
+except ValueError:
+    main_version, minor_version = version.split(".")  # e.g. 1.78
+    dev_version = False
+prev_minor_version = int(minor_version) - (2 if dev_version else 1)
+previous_version = f"{main_version}.{prev_minor_version}"
+versions = [
+    ("Previous", f"../../{previous_version}/api/"),
+    ("Latest", "../../latest/api/"),
+    ("Develop", "../../dev/api/"),
+]
+
+if version < "1.75":  # 1.74 is the earliest Sphinx-generated api documentation
+    del versions[0]
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -92,7 +111,9 @@
 }
 
 # To avoid import errors.
-autodoc_mock_imports = ["MySQLdb", "Bio.Restriction.Restriction", "Bio.Alphabet"]
+autodoc_mock_imports = ["MySQLdb", "Bio.Restriction.Restriction"]
+if version > "1.77":
+    autodoc_mock_imports.append("Bio.Alphabet")
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -118,9 +139,16 @@
     "github_version": "master",
     "conf_py_path": "/Doc/api/",
     # "source_suffix": source_suffix,
+    "theme_display_version": False,
+    # Biopython-specific values for version-footer (versions.html):
+    "display_version_footer": True,
+    "current_version": version,
+    "versions": versions,
+    "project_home_url": "https://biopython.org",
+    "project_github_url": "https://github.com/biopython/biopython",
 }
 
-html_logo = "../images/biopython_logo.svg"
+html_logo = "../images/biopython_logo_white.png"
 
 # The RST source is transient, don't need/want to include it
 html_show_sourcelink = False
@@ -131,20 +159,21 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+# The following is not applicable to the Read-the-docs theme:
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "relations.html",  # needs 'show_related': True theme option to display
-        "searchbox.html",
-        "donate.html",
-    ]
-}
+# html_sidebars = {
+#     "**": [
+#         "about.html",
+#         "navigation.html",
+#         "relations.html",  # needs 'show_related': True theme option to display
+#         "searchbox.html",
+#         "donate.html",
+#     ]
+# }
 
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -310,6 +339,8 @@ def setup(app):
     """Over-ride Sphinx setup to trigger sphinx-apidoc."""
     app.connect("builder-inited", run_apidoc)
 
+    app.add_css_file("biopython.css")
+
     def add_documenter(app, env, docnames):
         app.add_autodocumenter(BioPythonAPI, True)
 


Test patch: