Different black colors in sidebar of documentation

[MarkusPiotrowski]

The top part of the sidebar in the documentation, containing the logo and the version, has a darker black color (as set manually in the 'config.py' for Sphinx) than the rest of the sidebar (which has a grayish touch).

Do we want to retain this difference (visually separating the 'header' of the sidebar from the rest), or make it identical, like in the rest of the Biopython pages?

The grayish touch is from the original 'Read the Docs' template, but they use a different color scheme for the sidebar (blue in header, light black in main part, dark black for footer).

[peterjc]

GitHub pages using Hyde theme: https://biopython.org/ (etc), controlled from https://github.com/biopython/biopython.github.io/tree/master/assets/css etc)

Sphinx pages using RTD theme: https://biopython.org/docs/dev/api/ (etc), controlled from https://github.com/biopython/biopython/blob/master/Doc/api/conf.py etc

Also the text "biopython" under the logo is white vs grey, and the side bar width is not quite the same either.

Personally I think being more consistent would be best - and either or both styles can be edited to reach that goal. I would guess a single background colour is easier to achieve?

Shall we tag this as a help-wanted enhancement & add some more pointers to how this is currently setup?

[MarkusPiotrowski]

Interestingly, in my local builds the sidebar width (of the documentation) is smaller (but still different to biopython.org).

I had made some progress regarding some issues that I mentioned here (https://github.com/biopython/DIST/pull/8#issuecomment-690223304), so let me give it a try.

[MarkusPiotrowski]

Regarding version switching, it would be helpful if the documentation of the last stable release would have a fixed address, e.g. '.../docs/stable/api' or '.../docs/latest/api'

[peterjc]

Yes, that would be helpful. Do you know if GitHub pages will respect a symlink? If so, that would be the simplest way to do this on https://github.com/biopython/docs/

[MarkusPiotrowski]

That's what I have so far. The Biopython logo links to the Biopython.org documentation page (where one probably has started to enter the api docs), The small "link bar" links to the latest release ('Stable') (should be possible to use a symlink here), to the dev documentation ('Latest') and to the release before the displayed one (in this example it would link to 1.75).

The whole thing is a bit hack-ish, I had to change config.py, make an additional .css file and make a copy of a modified layout.html.

The width of the sidebar is still different, but this seems also to be dependent on the screen and/or window size. Hyde and RTD use different approaches for the sizing and I wonder if we can get it 100% identical withoug largely changing one of both .css files.

I'll see if I can push this somewhere for testing, not sure about this, I think I can only have one repository with gh pages as a private person.

[JoaoRodrigues]

Markus,

First thing: this looks super nice!

Second thing: You can have a gh-page per repository. So you could have a gh-pages branch on your biopython-docs fork and access it like username.github.io/biopython-docs.

[MarkusPiotrowski]

João, thanks, but most of it was already there before (https://biopython.org/docs/1.78/api/), I just played around with the sidebar.

By your 'Pro' label I see that you have a paid GitHub account that I haven't, but I'll test if I can get this published with gh-pages.

[JoaoRodrigues]

I like the uniform color of the sidebar and the more contrasting colors :)

I got a free Pro account with my academic email address. It's available for researchers and faculty as well, not only students. But I don't think it's necessary. You'd only need the Pro account for private repositories.

[MarkusPiotrowski]

That's an alternative, more clean version, with the version switching hidden in the footer of the sidebar:

If you click on the footer, it looks so:

The color and background of the footer can be changed (I guess...).

With this solution we could theoreticall fill the footer with all doc versions, but I think just having the three 'Previous', 'Stable' and 'Latest' will suffice and is probably more handy?

[peterjc]

The footer placement matches how RTD does it, so should be very familiar to lots of readers. +1

I have no strong view on which versions (all or previous/stable/latest) to list - I would lean to whatever is easier to maintain.

[MarkusPiotrowski]

@JoaoRodrigues Your are right, each repository can be added to GitHub pages! After forking, you just need to go to the settings, which has a Github Pages section and there you can even select the branch that is published. Nice.

[MarkusPiotrowski]

You can check the updated design for the documentation now here: https://markuspiotrowski.github.io/docs/1.76/api/index.html

Please note:

• For now, this is only applied to version 1.76
• This is not the whole documentation (for testing I deleted many files for the sake of speed)

When I got your OK I will rebuild and replace the existing documentations (except for the dev folder) one by one and then make a PR in biopython/biopython for the automatic setup.

[peterjc]

Design looks good to me.

I guess if you apply the configuration changes to https://github.com/biopython/biopython/blob/master/Doc/api/conf.py and the templates etc, then the https://biopython.org/docs/dev/api/ will get the new look automatically?

[JoaoRodrigues]

👍 looks good!

[MarkusPiotrowski]

I guess if you apply the configuration changes to https://github.com/biopython/biopython/blob/master/Doc/api/conf.py and the templates etc, then the https://biopython.org/docs/dev/api/ will get the new look automatically?

That's the idea. @peterjc Can you push a symlink to biopython/docs pointing from stable/api to 1.78/api? It turned out that I'm not able to create a proper/working symlink with Git for Windows ($ ln -s ... always makes a copy instead of creating the symlink. Google and SO tricks didn't help for me).

[peterjc]

See https://github.com/biopython/docs/pull/2 just tested at https://peterjc.github.io/docs/latest/api/