updating theme to pandas sphinx

[choldgraf]

This updates the theme to the new pandas sphinx theme, it adds a few extra pages, but it does not change the URLs of any pre-existing pages.

[choldgraf]

Hmmm I'm not sure why CircleCI is not showing up here, has anyone else noticed docs builds not happening on repo2docker?

(also, it seemed like the error with the earlier build was on the stencila-r job, it was a hang which makes me think it's unrelated to this PR)

[betatim]

I've not paid attention to the circleci build, so not sure if has been broken for a while or not :( Now it is only the code coverage check that fails (maybe something to investigate because changing the docs shouldn't change the coverage -> for a new issue though).

No idea why circleci doesn't run :(

[betatim]

Maybe because you are pushing to branches in this repo (which I think we shouldn't do :) ) instead of having your branch in your fork? In travis you can configure things to only run for PRs but not pushes, maybe CircleCI has a similar feature?

[choldgraf]

re: pushing to branches, I'm a bit confused by what you mean. Isn't my branch attached to my org? (https://github.com/choldgraf/repo2docker/tree/theme)

re: code coverage....yeah I'm not sure what to do about this since none of these changes are touching code (outside of the docs) or tests 🤔

[betatim]

Apologies, I didn't look properly: it looked like you pushed a branch to this repo instead of your fork. Then I am officially out of ideas as to why CircleCI doesn't get triggered. It did run for a PR a few days ago so I will close and re-open this PR to see what that does.

[choldgraf]

ok weird, I just opened up a new PR here: #817 with a dummy commit and it does trigger circleci throws up hands

I also tried opening up a new PR from my repo and it also didn't work. So:

• PR on a branch from jupyter/ repo: ✔️
• PR from @choldgraf's branch: ❌

Anybody else wanna try opening a quick PR from their branch to see if this works?

[betatim]

#820 triggered a build. Have you looked at the settings of your repo2docker project for CircleCI? I am 80% sure that your personal settings/fork settings don't influence stuff here but you never know. This situation should already not be happening :-/

[choldgraf]

ah hah, I think I figured it out. Somehow circleci had started building my repo2docker fork on top of the jupyter/repo2docker one. And so I think what happened is that it was treating the jupyter repo2docker PRs as "redundant" and not building them.

Here are the docs:

https://861-90722372-gh.circle-artifacts.com/0/html/index.html

Now we can get to actually critiquing this PR haha

[betatim]

I think it looks good.

One thing that is weird is that some of the headings are "links". For example if you go to https://861-90722372-gh.circle-artifacts.com/0/html/config_files.html#environment-yml-install-a-python-environment that heading is styled like a link. But other headings like https://861-90722372-gh.circle-artifacts.com/0/html/howto/user_interface.html#nteract aren't. Figuring out how we can get both to not be styled like a hyperlink would be cool.

The other thing I checked is use http://khan.github.io/tota11y/ on the new docs. It has a few complaints about contrast. Is this something we can upstream? It even makes suggestions for other colours to use that have enough contrast so it could be an easy set of changes.

[choldgraf]

Ah - I believe that's actually because of the contents:: directive on the page, which was causing all of the headers to be rendered as links. I just removed it, since it's redundant with the sidebar to the right, and the headings now look normal. Does that work?

re: a11y and upstreaming, we can definitely improve upon this. I've been upstreaming a bunch of stuff to https://github.com/pandas-dev/pandas-sphinx-theme already, and I think the general plan is to eventually move this out of the pandas-dev org and into pydata, and call it something like sphinx-pydata.

I also opened up an issue about a11y here: pydata/pydata-sphinx-theme#61

[consideRatio]

I did a git pull to z2jh recently to update my local master branch, and found this summary of relocated files etc. Concusion, git can be helpful to track this!

51 files changed, 194 insertions(+), 123 deletions(-)
 rename doc/source/{ => administrator}/advanced.md (100%)
 rename doc/source/{ => administrator}/architecture.rst (91%)
 rename doc/source/{ => administrator}/authentication.rst (100%)
 rename doc/source/{ => administrator}/cost.rst (100%)
 rename doc/source/{ => administrator}/debug.rst (100%)
 create mode 100644 doc/source/administrator/index.rst
 rename doc/source/{ => administrator}/optimization.md (100%)
 rename doc/source/{ => administrator}/security.md (94%)
 rename doc/source/{ => administrator}/troubleshooting.rst (100%)
 rename doc/source/{ => administrator}/upgrading.md (100%)
 rename doc/source/{ => community}/additional-resources.rst (100%)
 create mode 100644 doc/source/community/index.rst
 rename doc/source/{ => community}/tips.rst (100%)
 rename doc/source/{ => community}/users-list.md (100%)
 rename doc/source/{ => customizing}/extending-jupyterhub.rst (100%)
 create mode 100644 doc/source/customizing/index.rst
 rename doc/source/{ => customizing}/user-environment.rst (100%)
 rename doc/source/{ => customizing}/user-management.md (97%)
 rename doc/source/{ => customizing}/user-resources.rst (100%)
 rename doc/source/{ => customizing}/user-storage.md (100%)
 delete mode 100644 doc/source/getting-started.rst
 rename doc/source/{ => reference}/glossary.rst (100%)
 create mode 100644 doc/source/reference/index.rst
 rename doc/source/{ => reference}/reference-docs.rst (100%)
 rename doc/source/{ => reference}/reference.txt (100%)
 rename doc/source/{ => reference}/tools.rst (100%)
 create mode 100644 doc/source/setup-jupyterhub/index.rst
 rename doc/source/{ => setup-jupyterhub}/setup-helm.rst (100%)
 rename doc/source/{ => setup-jupyterhub}/setup-jupyterhub.rst (100%)
 rename doc/source/{ => setup-jupyterhub}/turn-off.rst (100%)

[betatim]

Merged! We can address the "linkified headers" in a new PR.