TypeError: add_source_parser() positional arguments error in Sphinx v3.0.0

[matthewfeickert]

Describe the bug
In pyhf's nightly CI we noticed that our build of our docs fails with the release of Sphinx v3.0.0

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

The exact same code passed the nightly build the night before with Sphinx v2.4.4.

To Reproduce
Steps to reproduce the behavior:

$ git clone https://github.com/scikit-hep/pyhf.git
$ cd pyhf
$ python -m pip install --ignore-installed -U -q --no-cache-dir -e .[docs,test]
$ cd docs
$ make html

For additional reference, our GitHub Actions workflow is here.

Expected behavior
The docs successfully build.

Your project

pyhf Issue 818

Environment info

• OS: Linux Ubuntu 19.10 (and whatever Linux the GitHub Actions ubuntu-latest is)
• Python version: 3.7.5
• Sphinx version: 3.0.0
• Sphinx extensions:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinxcontrib.bibtex',
    'sphinx.ext.napoleon',
    'sphinx_click.ext',
    'nbsphinx',
    'm2r',
    'sphinx_issues',
    'sphinx_copybutton',
    'xref',
]

Additional context
pyhf Issue 818

[CrossNox]

Having the same issue on gitlab-ci with

extensions = [
    'sphinx.ext.napoleon',
    'sphinx.ext.autodoc',
    'm2r'
]

[tk0miya]

Since 1.8.0, the suffix argument for app.add_source_parser() has been deprecated. And it is removed now.

sphinx/CHANGES

Lines 1323 to 1324 in 713bbf5

	* ``app.add_source_parser()`` has changed; the *suffix* argument has been
	deprecated

And it has also been reported at m2r project (miyakogi/m2r#51). I think m2r should be updated to use new API.

Thanks,

[matthewfeickert]

@CrossNox Thanks for your PR to m2r. As the project hasn't had a release since 2018 though my guess is that it is in archive mode and your PR will never get reviewed and merged. If you find another suitable extension can you share it here?

[CrossNox]

@matthewfeickert sure, I'll have to search a replacement eventually. For now, we've pointed the dependency to my fork to test it. m2r's owner doesn't seem to have been active since last june :(

[matthewfeickert]

@CrossNox @halfak it might be worth (for all of our projects) checking how Black is able to use Makrdown but doesn't use m2r. Maybe if they have time (before I do to go step through it) @ambv, @willingc, or @cooperlees could comment RE: that.