Repository: scikit-hep/pyhf

Issue:
Bug Report: Sphinx v3.0.0 breaks docs build
# Description

The release of Sphinx [`v3.0.0`](https://github.com/sphinx-doc/sphinx/releases/tag/v3.0.0) [breaks the build of the docs with](https://github.com/scikit-hep/pyhf/runs/562901637?check_suite_focus=true#step:6:11)

```pytb
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

- [x] Run `git fetch` to get the most up to date version of `master`
- [x] Searched through existing Issues to confirm this is not a duplicate issue
- [x] 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



Discussion:
This will get fixed if https://github.com/miyakogi/m2r/pull/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.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,7 +51,6 @@ def setup(app):
     'sphinx.ext.napoleon',
     'sphinx_click.ext',
     'nbsphinx',
-    'm2r',
     'sphinx_issues',
     'sphinx_copybutton',
     'xref',
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -2,8 +2,8 @@
 from pathlib import Path
 
 this_directory = Path(__file__).parent.resolve()
-with open(Path(this_directory).joinpath('README.md'), encoding='utf-8') as readme_md:
-    long_description = readme_md.read()
+with open(Path(this_directory).joinpath('README.rst'), encoding='utf-8') as readme_rst:
+    long_description = readme_rst.read()
 
 extras_require = {
     'tensorflow': ['tensorflow~=2.0', 'tensorflow-probability~=0.8'],
@@ -60,7 +60,6 @@
             'ipywidgets',
             'sphinx-issues',
             'sphinx-copybutton>0.2.9',
-            'm2r',
         ]
     )
 )
@@ -79,7 +78,7 @@
     version='0.4.1',
     description='(partial) pure python histfactory implementation',
     long_description=long_description,
-    long_description_content_type='text/markdown',
+    long_description_content_type='text/x-rst',
     url='https://github.com/scikit-hep/pyhf',
     author='Lukas Heinrich, Matthew Feickert, Giordon Stark',
     author_email='lukas.heinrich@cern.ch, matthew.feickert@cern.ch, gstark@cern.ch',


Test patch:
diff --git a/.github/workflows/release_tests.yml b/.github/workflows/release_tests.yml
--- a/.github/workflows/release_tests.yml
+++ b/.github/workflows/release_tests.yml
@@ -22,6 +22,12 @@ jobs:
       uses: actions/setup-python@v1
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Free disk space
+      # WARNING: Needed due to GitHub Actions disk space regression on Linux runners
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        sudo apt-get clean
+        df -h
     - name: Install from PyPI
       run: |
         python -m pip install --upgrade pip setuptools wheel
diff --git a/tests/test_scripts.py b/tests/test_scripts.py
--- a/tests/test_scripts.py
+++ b/tests/test_scripts.py
@@ -46,10 +46,7 @@ def test_import_prepHistFactory_withProgress(tmpdir, script_runner):
 
 
 def test_import_prepHistFactory_stdout(tmpdir, script_runner):
-    temp = tmpdir.join("parsed_output.json")
-    command = 'pyhf xml2json validation/xmlimport_input/config/example.xml --basedir validation/xmlimport_input/'.format(
-        temp.strpath
-    )
+    command = 'pyhf xml2json validation/xmlimport_input/config/example.xml --basedir validation/xmlimport_input/'
     ret = script_runner.run(*shlex.split(command))
     assert ret.success
     assert ret.stdout != ''
@@ -158,14 +155,12 @@ def test_patch(tmpdir, script_runner):
     ret = script_runner.run(*shlex.split(command))
     assert ret.success
 
-    command = 'pyhf cls {0:s} --patch -'.format(temp.strpath, patch.strpath)
+    command = f'pyhf cls {temp.strpath:s} --patch -'
 
     ret = script_runner.run(*shlex.split(command), stdin=patch)
     assert ret.success
 
-    command = 'pyhf json2xml {0:s} --output-dir {1:s} --patch -'.format(
-        temp.strpath, tmpdir.mkdir('output_2').strpath, patch.strpath
-    )
+    command = f"pyhf json2xml {temp.strpath:s} --output-dir {tmpdir.mkdir('output_2').strpath:s} --patch -"
     ret = script_runner.run(*shlex.split(command), stdin=patch)
     assert ret.success