Fixes #5285 upgrades sphinx for developer requirements

[kushaldas]

Status

Ready for review

Description of Changes

Fixes #5285

Upgrades sphinx version.

Also adds proper code block value at 3 places in the documentation.

Testing

• test make lint command output.

Deployment

Any special considerations for deployment? Consider both:

1. Upgrading existing production instances.
2. New installs.

Checklist

If you made changes to the server application code:

• Linting (make lint) and tests (make test) pass in the development container

If you made changes to securedrop-admin:

• Linting and tests (make -C admin test) pass in the admin development container

If you made changes to the system configuration:

• Configuration tests pass

If you made non-trivial code changes:

• I have written a test plan and validated it for this PR

If you made changes to documentation:

• Doc linting (make docs-lint) passed locally

If you added or updated a code dependency:

Choose one of the following:

• I have performed a diff review and pasted the contents to the packaging wiki
• I would like someone else to do the diff review

[kushaldas]

Failed with

  Downloading https://files.pythonhosted.org/packages/74/3d/1ee25a26411ba0401b43c6376d2316a71addcc72ef8690b101b4ea56d76a/zipp-0.6.0-py2.py3-none-any.whl
Requirement already satisfied: pip==19.1 in /opt/venvs/securedrop-app-code/lib/python3.5/site-packages (from -r requirements/python3/develop-requirements.txt (line 694)) (19.1)
Requirement already satisfied: setuptools==46.0.0 in /opt/venvs/securedrop-app-code/lib/python3.5/site-packages (from -r requirements/python3/develop-requirements.txt (line 697)) (46.0.0)
Collecting importlib-resources; python_version < "3.7" (from pre-commit==1.18.3->-r requirements/python3/develop-requirements.txt (line 407))
ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. These do not:
    importlib-resources; python_version < "3.7" from https://files.pythonhosted.org/packages/7f/2d/88f166bcaadc09d9fdbf1c336ad118e01b7fe1155e15675e125be2ff1899/importlib_resources-1.5.0-py2.py3-none-any.whl#sha256=85dc0b9b325ff78c8bef2e4ff42616094e16b98ebd5e3b50fe7e2f0bbcdcde49 (from pre-commit==1.18.3->-r requirements/python3/develop-requirements.txt (line 407))
WARNING: You are using pip version 19.1, however version 20.1.1 is available.

Found the issue, I have to mark it manually.

[kushaldas]

Also possible error with pygments, I will have to upgrade that too.

███ Linting documentation...
make[1]: Entering directory '/home/kdas/code/securedrop/docs'
rm -rf _build/*
make[1]: Leaving directory '/home/kdas/code/securedrop/docs'
Running Sphinx v3.0.4
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 81 source files that are out of date
updating environment: [new config] 81 added, 0 changed, 0 removed
reading sources... [100%] yubikey_setup                                                                                                                                      
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] yubikey_setup                                                                                                                                       

Warning, treated as error:
/home/kdas/code/securedrop/docs/development/virtualizing_tails.rst:72:Could not lex literal_block as "python". Highlighting skipped.
make: *** [Makefile:87: docs-lint] Error 2

[emkll]

Thanks @kushaldas for the changes,the diff looks good visually to me, and CI is passing. However, as I was clicking around the interface to look at the codeblock changes rendered, I observed an error:

On sphinx 3.0.4, any link that appears in the search results is not clickable (undefined instead of .html in the URL). Reverting back to the 3 year old version does resolve, see below

3.0.4:

1.6.3:

seems like perhaps a config has changed in Sphinx 3.x?

Error logs returns a basic 404 with no further useful information:

[W 200602 09:06:09 web:2063] 404 GET /development/virtualizing_tailsundefined?highlight=virtualizing%20tails (127.0.0.1) 3.65ms

[kushaldas]

@emkll that is an excellent find. I am searching for answer/fix.

[kushaldas]

Found the issue, our theme was also million years old :D Now upgraded to a modern one. @emkll you can have a look after CI is green.

[emkll]

Thanks for the quick fixes, changes look good to merge when CI passes.
I've observed some minor differences as a side-effect of the theme update (see below), but good to merge without further changes to unblock CI.

left: new theme right: old theme

[kushaldas]

Yes, as we use a theme written by someone else, we have to use what ever they provide.

[eloquence]

Per discussion at standup, prior to merge, I'll do a bit of regression testing locally esp. focused on the theme changes.

[eloquence]

No objections from me to merging this PR. The only thing I'm noticing that I would characterize as a regression due to the new theme is that links in definitions are no longer clearly identifiable due to the formatting. The only page I was able to spot where this is an issue is

https://docs.securedrop.org/en/master/development/apt_repo.html

which looks like this in the new theme:

Note that you can no longer tell which of the headings are clickable. Otherwise, the new style does make apparent a few more existing formatting issues with our docs, such as this:

This bullet list item should really not be formatted as a definition (it's bold in the old theme, which is also incorrect). So in my view there's a couple of minimal follow-up actions:

• move some links around for clarity, or otherwise work around issue above
• clear up legacy formatting issues that are now more visible

We could also override the new styling, but to minimize maintenance effort, it may be best to stick with the stock theme for now until we really replace it with something custom.

[conorsch]

Good points from @eloquence noting the slight regressions. Fine for now, let's keep an eye out for further improvements as we step through the docs prior to release.