Bug Report: Sphinx v3.0.0 breaks docs build

[matthewfeickert]

Description

The release of Sphinx v3.0.0 breaks the build of the docs with

Exception occurred:
  File "/opt/hostedtoolcache/Python/3.7.6/x64/lib/python3.7/site-packages/sphinx/application.py", line 1069, in add_source_parser
    self.registry.add_source_parser(*args, **kwargs)
TypeError: add_source_parser() takes 2 positional arguments but 3 were given
The full traceback has been saved in /tmp/sphinx-err-gu866l6p.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!

which when run locally the generated log is

$ cat /tmp/sphinx-err-blah.log
# Sphinx version: 3.0.0
# Python version: 3.7.5 (CPython)
# Docutils version: 0.16 release
# Jinja2 version: 2.11.1
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "/home/feickert/.venvs/pyhf-dev/lib/python3.7/site-packages/sphinx/cmd/build.py", line 279, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/feickert/.venvs/pyhf-dev/lib/python3.7/site-packages/sphinx/application.py", line 244, in __init__
    self.setup_extension(extension)
  File "/home/feickert/.venvs/pyhf-dev/lib/python3.7/site-packages/sphinx/application.py", line 398, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/feickert/.venvs/pyhf-dev/lib/python3.7/site-packages/sphinx/registry.py", line 414, in load_extension
    metadata = setup(app)
  File "/home/feickert/.venvs/pyhf-dev/lib/python3.7/site-packages/m2r.py", line 652, in setup
    app.add_source_parser('.md', M2RParser)
  File "/home/feickert/.venvs/pyhf-dev/lib/python3.7/site-packages/sphinx/application.py", line 1069, in add_source_parser
    self.registry.add_source_parser(*args, **kwargs)
TypeError: add_source_parser() takes 2 positional arguments but 3 were given

Steps to Reproduce

Try to build the docs with Sphinx v3.0.0 or check the nightly CI builds.

Checklist

• Run git fetch to get the most up to date version of master
• Searched through existing Issues to confirm this is not a duplicate issue
• Filled out the Description, Expected Behavior, Actual Behavior, and Steps to Reproduce sections above or have edited/removed them in a way that fully describes the issue

[matthewfeickert]

This will get fixed if miyakogi/m2r#55 gets merged and a new release gets cut, but m2r hasn't had a release since 2018, so the project is probably in archive mode and we might need to find a new extension to use.

[matthewfeickert]

@kratsg @lukasheinrich Potentially relevant: sphinx-doc/sphinx#7420 (comment). I have this almost working on branch test/try-without-m2r-extension.

[matthewfeickert]

I'm trying to get this working by using Pandoc to convert the README.md into README.rst and then just doing

.. include:: ../README.rst

in our index.rst. However,

pandoc ../README.md --from markdown --to rst -s -o ../README.rst

doesn't preserve our hyperlinked images.

pandoc ../README.md --from markdown-markdown_in_html_blocks+raw_html --to rst --output ../README.rst

almost gets it, but it doesn't preserve the Brazil band plots.

If we can figure out the images then we're good to go. @kratsg Do you know any Pandoc tricks that I havn't found on Stack Overflow yet?

[kratsg]

I converted it in the PR.

[matthewfeickert]

I converted it in the PR.

Yes, what I mean is having Pandoc do automatic conversion when you type make html so that you can keep the Markdown.

[kratsg]

Won't be possible. It's easier if we just convert because then we ahve to deal with changes to pandoc later (it's another dependency...)

…

On Wed, Apr 8, 2020 at 10:50 AM Matthew Feickert ***@***.***> wrote: I converted it in the PR. Yes, what I mean is having Pandoc do automatic conversion when you type make html so that you can keep the Markdown. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#818 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFZ5C6UFHK3ZQIB5UICAQLRLSFKLANCNFSM4MCAZUPA> .

-- Dr. Giordon Stark (pronouns: he/him) ATLAS Post-doctoral scholar employee at SCIPP/UCSC https://giordonstark.com/ <https://giordonstark.com/?utm_source=kratsg@gmail.com&utm_medium=email_signature>

[kanishk16]

This thought has bugged me for a couple of days, is there any particular reason for preferring markdown over rST here?

[matthewfeickert]

is there any particular reason for preferring markdown over rST here?

Markdown is very simple and easy to write and is abundant across the internet. rST is very powerful, but harder for new users to write. If you look at the branch for PR #819 you'll also note that GitHub doesn't render the images in README.rst correctly, given its parsers — though the docs are obviously rendered correctly.

I think to move forward it is probably best to just adopt rst here and see if we can figure out a way to go back to the Markdown ways in the future.