switched sphinx theme with MDAnalysis styling

[orbeckst]

Fixes #378

Changes made in this Pull Request:

• switch sphinx theme to alabaster
• small style changes to adapt to MDAnalysis home page look and feel

See screenshot for what it looks like:

PR Checklist

• works locally?
• n/a Docs?
• CHANGELOG updated?
• Issue raised/referenced?

Problems

I can't build the docs locally at the moment: sphinx.autodoc appears to fail.

[orbeckst]

Figured out why autodoc wasn't working... I overwrote extensions due to mindless copy & paste.

[orbeckst]

In order to review you need to build locally. I used a virtual env. If you do this, make sure to install sphinx into the venv or otherwise it will fail to pick up packages. If all goes well:

cd package/doc/sphinx
make html
open ../html/index.html

[orbeckst]

Some things aren't great yet

• the author footer can overlap with the sidebar on pages with little content
• not sure if I like orange underbar for links to objects/functions (which remain black although we can probably make them orange if we want to)
• not using MDA gray anywhere
• code block boxes extend to far in docs
• code font size seems to big
• Narrow sidebar (for narrow window) does not look good (black links on dark-gray bg, maybe use MDA gray)
• sidebar TOC is static (does not give you any indication where you are, unlike RTD)

Notes on customization:

• configuration in package/doc/sphinx/source/conf.py
• set theme options, try to avoid explicit CSS (although that's also possible)
• note: CSS lists must be written as Python strings (not as Python lists)
• True and False seem to work

[kain88-de]

@orbeckst sorry for not looking over this earlier. I should have some time this week to look over the changes.

[kain88-de]

Which version of sphinx are you using? I'm getting build errors with 1.5 also on the master branch

[orbeckst]

Latest sphinx from pip. If you use a venv install sphinx into the venv. What's the error?

…

-- Oliver Beckstein email: orbeckst@gmail.com

Am Dec 20, 2016 um 8:05 schrieb Max Linke ***@***.***>: Which version of sphinx are you using? I'm getting build errors with 1.5 also on the master branch — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[kain88-de]

Yes I have sphinx installed in the conda environment. Here is the error I'm getting

(mda-py2) thinki doc/sphinx ‹develop*› » make html
sphinx-build -b html   source ../html
Running Sphinx v1.5
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/2/objects.inv
loading intersphinx inventory from http://docs.scipy.org/doc/scipy/reference/objects.inv...
intersphinx inventory has moved: http://docs.scipy.org/doc/scipy/reference/objects.inv -> https://docs.scipy.org/doc/scipy/reference/objects.inv
loading intersphinx inventory from http://matplotlib.org/objects.inv...
loading intersphinx inventory from https://networkx.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from http://docs.scipy.org/doc/numpy/objects.inv...
intersphinx inventory has moved: http://docs.scipy.org/doc/numpy/objects.inv -> https://docs.scipy.org/doc/numpy/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 126 source files that are out of date
updating environment: 126 added, 0 changed, 0 removed
reading sources... [ 10%] documentation_pages/analysis/encore/similarity                                 
Exception occurred:
  File "/home/max/anaconda2/lib/python2.7/site-packages/sphinx/domains/std.py", line 543, in note_citations
    path = env.doc2path(self.data['citations'][0])
KeyError: 0
The full traceback has been saved in /tmp/sphinx-err-ChKK5K.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:42: recipe for target 'html' failed

[kain88-de]

OK with sphinx=1.4.8 I can compile the docs. It doesn't work with 1.5 and later.

[kain88-de]

the author footer can overlap with the sidebar on pages with little content

also when scrolling towards the bottom.

I have some more errors. On my laptop screen I can't see the fill side bar. Neither can I scroll the sidebar.

It is very hard for me to see where an old function stops and a new function starts. Even worse the note and other boxes are much much more prominent then the actual function and arguments.

[kain88-de]

I found an awesome-list for sphinx. They have a theme for autodoc generated docs https://sphinx-readable-theme.readthedocs.io/en/latest/. What I like in that theme is that the line with the function name is highlighted from the background which makes it easy to see when I have a new function.

[orbeckst]

The theme has nice features. Can it be customized, namely colors, typeface and logo?

…

-- Oliver Beckstein email: orbeckst@gmail.com

Am Dec 20, 2016 um 15:17 schrieb Max Linke ***@***.***>: I found an awesome-list for sphinx. They have a theme for autodoc generated docs https://sphinx-readable-theme.readthedocs.io/en/latest/. What I like in that theme is that the line with the function name is highlighted from the background which makes it easy to see when I have a new function. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[orbeckst]

I think the sidebar can be made non-floating and just part of the page. I agree with your assessment that the autodocs are not very readable. But this said, if we find a better theme I'm all for it. I just want it to look distinct and matching to some degree our web page. This really amounts to just a few CSS changes but if this can be done with theme variables in the conf.py then that makes life a lot easier.

…

-- Oliver Beckstein email: orbeckst@gmail.com

Am Dec 20, 2016 um 15:06 schrieb Max Linke ***@***.***>: the author footer can overlap with the sidebar on pages with little content also when scrolling towards the bottom. I have some more errors. On my laptop screen I can't see the fill side bar. Neither can I scroll the sidebar.

[dotsdl]

@orbeckst is this still WIP? Or do you want review followed by merge?

[kain88-de]

This is still WIP. The sidebar is an issue and the theme makes the config harder to read IMHO. I didn't have time to try out any of the other themes I linked to above.

[orbeckst]

This is currently just a test bed and not to be merged.

[orbeckst]

I played around with the alabaster scheme and I am actually pretty happy with the result; at least I like it better than the old theme. You can see it at http://www.mdanalysis.org/docs/

With a little bit of hacking in custom.css we can probably also get the highlighting of methods as in https://sphinx-readable-theme.readthedocs.io/en/latest/#example.Storage working. Alternatively, feel free to do a PR with the sphinx-readable theme (you can use this one because it should not be too hard to move between them... or do a PR onto this one).

The deploy_master_docs.sh script is not yet ready for travis (see #1315 (comment)) but everything else should work.

Anyway, comments, please.

[orbeckst]

I also tried a customized version of sphinx-readable-theme as suggested by @kain88-de and it looks rather nice. You can compare the two styles:

• readable: https://orbeckst.github.io/mdanalysis_docs/
• alabaster: http://mdanalysis.org/docs

alabaster has better configuration options via the conf.py file, it can do fancy things with the navigation in the sidebar (unfold the current section that one is in), and it has nice little additions such as travis build status and GitHub links.

readable has really nice autodoc sections and overall slightly cleaner layout.

@MDAnalysis/coredevs , which theme would you like? I'll then rewrite the PR into a few clean commits, ask for approval by review, and we'll have pretty docs.

[jbarnoud]

On 05/18/2017 10:51 AM, Oliver Beckstein wrote: I also tried a customized version of sphinx-readable-theme <https://sphinx-readable-theme.readthedocs.io/> as suggested by @kain88-de <https://github.com/kain88-de> and it looks rather nice. You can compare the two styles: * *readable*: https://orbeckst.github.io/mdanalysis_docs/ * *alabaster*: http://mdanalysis.org/docs *alabaster* <http://alabaster.readthedocs.io/en/latest/> has better configuration options via the conf.py file, it can do fancy things with the navigation in the sidebar (unfold the current section that one is in), and it has nice little additions such as travis build status and GitHub links. *readable* <https://sphinx-readable-theme.readthedocs.io/> has really nice autodoc sections and overall slightly cleaner layout. @MDAnalysis/coredevs <https://github.com/orgs/MDAnalysis/teams/coredevs> , which theme would you like? I'll then rewrite the PR into a few clean commits, ask for approval by review, and we'll have pretty docs. — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub <#1126 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABUWuoDAsiBrEW5FmsgKunCZvAFxqawqks5r7AZ5gaJpZM4LNj8P>.

I like "readable" better. The side bar looks a bit shy, though. Maybe it would deserve a slightly bigger logo, or a larger font, or a solid gray background.

[kain88-de]

I also prefer the readable version.

[mnmelo]

Graphically I prefer 'readable' (but I don't agree with @jbarnoud's call for a more emphasized sidebar).
However, it's a deal breaker for me that the sidebar doesn't unfold the section. If I'm looking for selection commands, for instance, I have to either click 'Contents' on the sidebar or scroll down till the Contents section. And only then I get to click on the 'Selection commands' link. It doesn't feel half as intuitive and fast as alabaster.

Is there a way to have the best of both worlds?

[orbeckst]

Is there a way to have the best of both worlds?

Probably yes, e.g., by overriding all of alabaster's CSS with readable.css. I can try it but to be honest, right now I don't have much more time to play around with this a lot more. I'll do another round of alabaster and if we then have at least one solution that is better than what we had before then either we take it or someone else starts fiddling. We can always improve things as we go along --- layout and docs will never be perfect.

[utkbansal]

Small question - why don't we use readthedocs to host our docs? That seems to be default choice to host docs by most of the python packages out there.

I'm thinking that readthedocs would have already figured out all the design and readability issues, why reinvent the wheel? Devs are already used to it.

Also its free and supports webhooks, so that can update docs on each commit. I think, right now @orbeckst does this manually every now and then - this might reduce some work too.

[orbeckst]

Fair question, mainly because a long time ago I got super-annoyed trying to get it to build on RTD (they did not support conda then). No-one else took it up since (I think) and so we are back to using GH pages. This works pretty well for the development docs already so we might as well do it. In any case, the styling is a different question from hosting. Personally, I am very much bored of the standard RTD style (even though it is quite functional). I am of the opinion that a reasonably sized project such as MDAnalysis also needs to have its own brand identity and so the goal is to have functional docs that are clearly "MDAnalysis". This means that our website and the docs should be using the same typefaces and base colours as well as the logo and overall have a recognizable look and feel. Furthermore, the docs should also be mobile friendly. Obviously, one can spend and infinite amount of time on CSS pixel pushing and doc refinement but if we can get something for the docs that's 80% ok I am happy.

…

On 18 May, 2017, at 11:06, Utkarsh Bansal ***@***.***> wrote: Small question - why don't we use readthedocs to host our docs? That seems to be default choice to host docs by most of the python packages out there.

-- Oliver Beckstein * orbeckst@gmx.net skype: orbeckst * orbeckst@gmail.com

[orbeckst]

Also its free and supports webhooks, so that can update docs on each commit. I think, right now @orbeckst does this manually every now and then - this might reduce some work too.

That's not a problem, we update our docs from travis builds.

Developer doc publication is fully automated and integrated in the CI and we will be doing this for the release docs as well (see #1315 ). Just for the playing around with themes I am pushing manually.

RTD has one advantage and that is they make it easy to switch between different versions.

Ultimately, I don't mind if someone else figures out to make it all work on RTD but time is a pretty precious resource...

[orbeckst]

I combined the readable styling with alabaster and you can see the latest version at http://mdanalysis.org/docs.

I am happy with it.

Either this or pure readable https://orbeckst.github.io/mdanalysis_docs/

[orbeckst]

Once I know what we want to do I will clean up the history in a few sensible commits. Please don't just squash.

[kain88-de]

Last iteration looks great and also works well on a tablet.

[orbeckst]

I rewrote the history of this PR into sensible units. Please merge as is (do not squash).

Compared to the last revision I also increased the level depth of headings in the navigation sidebar to 4; it's sometimes a bit more cluttered but I think it's important that even deep in analysis docs you can still navigate around, eg http://www.mdanalysis.org/docs/documentation_pages/analysis/hbond_analysis.html

@MDAnalysis/coredevs please have a look at http://www.mdanalysis.org/docs and if you are in general happy with this then I would like to merge this. (We can do more CSS adjustments and fine-tuning as we go along.)

The maintainer/deploy_master_docs.sh script was used in order to create the docs at http://www.mdanalysis.org/docs but will be properly integrated into Travis when we address #1315 .

[orbeckst]

PS: I am not 100% sure why the build status badge on the docs shows "error". It refers to the master branch (this is hard-coded in the alabaster theme as far as I can tell)

https://api.travis-ci.org/MDAnalysis/mdanalysis.svg?branch=master

I am not sure why it should show an error because looking at https://travis-ci.org/MDAnalysis/mdanalysis/branches our master branch is shown as green (although https://travis-ci.org/MDAnalysis/mdanalysis/builds/232796240 errored...) – any insights welcome.

[orbeckst]

Has any one of the current reviewers @kain88-de @dotsdl @tylerjereddy any further comments?

This needs at least one approval so that it can get merged.

@kain88-de : Please merge (and don't squash) because the commits are independent. Thanks.