Sphinx theme, navigation, and accessibility (a11y)

[intoverflow]

We need to decide on a Sphinx theme for the guide.

We also need to decide on the requirements for selecting a guide.

Two obvious requirements stand out (please add/discuss in the comments if you have feedback/suggestions on these):

• Ease of navigation on desktop, tablet, and mobile
• Accessibility (a11y), including aria tags, font & color pallet, etc

Proposed themes should be submitted as pull requests. Read the Docs is integrated with our continuous integration; this makes it easy to see how the theme looks with our content (and thus easy to evaluate whether or not it meets our requirements).

To ease tracking, please link your pull request with this issue.

[intoverflow]

Here are the PRs I've submitted so far:

• maisie-sphinx-theme #4
• sphinx-press-theme #5
• sphinx-sizzle-theme #6

Note that you must be logged into GitHub to see the continuous integration. The build preview can be seen by clicking the "Details" link on the Read the Docs build.

[bertiewooster]

Hello @intoverflow, the SymPy (open-source computer algebra system written in Python) team is also considering a new Sphinx theme for its documentation, and accessibility is an important criterion.

Any information you can share about your evaluation of the accessibility of Sphinx themes would be greatly appreciated--on Sphinx Themes, I didn't find any accessibility evaluations. I assume that the three themes you created pull requests for (maisie, Sphinx press, and sizzle) do well on accessibility?

[intoverflow]

Hi @bertiewooster, thank you for writing.

I haven't had a chance to have a serious evaluation performed, but I suspect each of these themes needs some changes to font color & size. I hope to update this issue (and the relevant PRs) later this week with some specific feedback from an a11y specialist. I'll ping you when I have that data

[bertiewooster]

@intoverflow I'm having trouble getting external themes such as Press to work. I followed the installation instructions:
$ pip install sphinx_press_theme
and used in conf.py:
html_theme = "press"
but I get the error

Theme error:
no theme named 'press' found (missing theme.conf?)
make: *** [Makefile:60: html] Error 2

I also tried adding, as you did, to doc/requirements.txt
sphinx-press-theme
but get the same error.

Any tips?

[intoverflow]

@bertiewooster In theory it should work. If you have a commit I'd be happy to test it on my environment to see if I can replicate the problem. Perhaps there's something going wrong with the python search paths? (This is just a guess.)

In case it's useful, I've provided some notes below about my build environments. I've also included a note about package names, but after some testing I no longer believe it's relevant to the issue you're facing.

My development environment

On my host, sphinx & sphinx_press_theme were both installed using pip. They can be found here:

~/.local/lib/python3.9/site-packages$ ls -d sphinx sphinx_press_theme
sphinx  sphinx_press_theme

readthedocs.org

I've configured readthedocs.org to build every pull request. Their tools use requirements.txt to determine which packages to install before building the docs. (I think they just run pip install -r requirements.txt and hope for the best.)

Package name

I noticed that your pip command and your requirements.txt file use different names for the package. At first I thought this might be relevant but now I am not so sure (see note below).

On closer inspection, it seems the Press installation instructions provides conflicting instructions. One calls the package sphinx-press-theme while the other calls it sphinx_press_theme:

I checked my local development machine to see which I had installed:

$ pip list | grep press
sphinx-press-theme            0.8.0

I tried installing "both" packages but, judging from the pip output, it appears they are synonyms:

$ pip install sphinx-press-theme sphinx_press_theme
Requirement already satisfied: sphinx-press-theme in /home/tcarstens/.local/lib/python3.9/site-packages (0.8.0)
Requirement already satisfied: sphinx>=4.0.1 in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx-press-theme) (4.3.1)
Requirement already satisfied: docutils<0.18,>=0.14 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (0.16)
Requirement already satisfied: snowballstemmer>=1.1 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (2.1.0)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx>=4.0.1->sphinx-press-theme) (2.0.0)
Requirement already satisfied: setuptools in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (52.0.0)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx>=4.0.1->sphinx-press-theme) (1.1.5)
Requirement already satisfied: sphinxcontrib-devhelp in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx>=4.0.1->sphinx-press-theme) (1.0.2)
Requirement already satisfied: Pygments>=2.0 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (2.7.1)
Requirement already satisfied: babel>=1.3 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (2.8.0)
Requirement already satisfied: sphinxcontrib-qthelp in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx>=4.0.1->sphinx-press-theme) (1.0.3)
Requirement already satisfied: Jinja2>=2.3 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (2.11.2)
Requirement already satisfied: requests>=2.5.0 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (2.25.1)
Requirement already satisfied: packaging in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (20.9)
Requirement already satisfied: alabaster<0.8,>=0.7 in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (0.7.8)
Requirement already satisfied: imagesize in /usr/lib/python3/dist-packages (from sphinx>=4.0.1->sphinx-press-theme) (1.2.0)
Requirement already satisfied: sphinxcontrib-applehelp in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx>=4.0.1->sphinx-press-theme) (1.0.2)
Requirement already satisfied: sphinxcontrib-jsmath in /home/tcarstens/.local/lib/python3.9/site-packages (from sphinx>=4.0.1->sphinx-press-theme) (1.0.1)

[bertiewooster]

@intoverflow thanks! I've tried several variations without luck. Here's a (draft) pull request where I've tried to get the Press theme to work.

In terms of my packages setup, I get the same results as you for these commands:

site-packages % ls -d sphinx sphinx_press_theme
sphinx			sphinx_press_theme

site-packages % pip list | grep press 
sphinx-press-theme            0.8.0

I build the Sphinx docs using Docker (per doc/Dockerfile.htmldoc), which works for the previous theme (classic).

# If SYMPY_ROOT is the directory where the sympy repository lives, then you can
# build the image with
#
#   $ cd SYMPY_ROOT/doc
#   $ docker build -f Dockerfile.htmldoc -t sympy_htmldoc .
#
# Once the image is built, you can build the docs at any time (and from any
# directory) using
#
#   $ docker run --rm -v /absolute/path/to/SYMPY_ROOT:/sympy sympy_htmldoc

I'm still getting the error

Theme error:
no theme named 'press' found (missing theme.conf?)
make: *** [Makefile:60: html] Error 2

[intoverflow]

Happy New Year! Adding @Cyndi206