🔧 MAINTAIN: Add publishing job for myst-docutils (#456)

This commit adds a workflow for releasing an additional package `myst-docutils`,
which does not include install requirements on docutils or sphinx.
This will allow the docutils package to utilise it as a dependency, with no cyclic dependencies.

The package is created by dynamically modifying the `setup.cfg` and `README.md` before the build.

The build is also tested against a range of docutils versions,
to ensure it does not fail due to the missing sphinx dependency.

.github/workflows/docutils_setup.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Script to convert package setup to myst-docutils."""
+import configparser
+import io
+import sys
+
+
+def modify_setup_cfg(content: str) -> str:
+    """Modify setup.cfg."""
+    cfg = configparser.ConfigParser()
+    cfg.read_string(content)
+    # change name of package
+    cfg.set("metadata", "name", "myst-docutils")
+    # move dependency on docutils and sphinx to extra
+    install_requires = []
+    sphinx_extra = [""]
+    for line in cfg.get("options", "install_requires").splitlines():
+        if line.startswith("docutils"):
+            sphinx_extra.append(line)
+        elif line.startswith("sphinx"):
+            sphinx_extra.append(line)
+        else:
+            install_requires.append(line)
+    cfg.set("options", "install_requires", "\n".join(install_requires))
+    cfg.set("options.extras_require", "sphinx", "\n".join(sphinx_extra))
+
+    stream = io.StringIO()
+    cfg.write(stream)
+    return stream.getvalue()
+
+
+def modify_readme(content: str) -> str:
+    """Modify README.md."""
+    content = content.replace(
+        "# MyST-Parser",
+        "# MyST-Parser\n\nNote: myst-docutils is identical to myst-parser, "
+        "but without installation requirements on sphinx",
+    )
+    content = content.replace("myst-parser", "myst-docutils")
+    content = content.replace("myst-docutils.readthedocs", "myst-parser.readthedocs")
+    content = content.replace(
+        "readthedocs.org/projects/myst-docutils", "readthedocs.org/projects/myst-parser"
+    )
+    return content
+
+
+if __name__ == "__main__":
+    setup_path = sys.argv[1]
+    readme_path = sys.argv[2]
+    with open(setup_path, "r") as f:
+        content = f.read()
+    content = modify_setup_cfg(content)
+    with open(setup_path, "w") as f:
+        f.write(content)
+    with open(readme_path, "r") as f:
+        content = f.read()
+    content = modify_readme(content)
+    with open(readme_path, "w") as f:
+        f.write(content)

.github/workflows/tests.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [master]
     tags:
-      - 'v*'
+      - "v[0-9]+.[0-9]+.[0-9]+*"
   pull_request:
 
 jobs:
@@ -17,22 +17,22 @@ jobs:
     - name: Set up Python 3.8
       uses: actions/setup-python@v1
       with:
-        python-version: 3.8
+        python-version: "3.8"
     - uses: pre-commit/action@v2.0.0
 
   tests:
 
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.6", "3.7", "3.8", "3.9"]
         sphinx: [">=4,<5"]
         os: [ubuntu-latest]
         include:
           - os: ubuntu-latest
-            python-version: 3.8
+            python-version: "3.8"
             sphinx: ">=3,<4"
           - os: windows-latest
-            python-version: 3.8
+            python-version: "3.8"
             sphinx: ">=4,<5"
 
     runs-on: ${{ matrix.os }}
@@ -61,10 +61,36 @@ jobs:
         file: ./coverage.xml
         fail_ci_if_error: true
 
+  check-myst-docutils:
+
+    name: Check myst-docutils install
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        docutils-version: ["0.16", "0.17", "0.18"]
+
+    steps:
+    - name: Checkout source
+      uses: actions/checkout@v2
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v1
+      with:
+        python-version: "3.8"
+    - name: Modify setup
+      run: python .github/workflows/docutils_setup.py setup.cfg README.md
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .
+        pip install docutils==${{ matrix.docutils-version }}
+    - name: Run docutils CLI
+      run: echo "test" | myst-docutils-html
+
   publish:
 
-    name: Publish to PyPi
-    needs: [pre-commit, tests]
+    name: Publish myst-parser to PyPi
+    needs: [pre-commit, tests, check-myst-docutils]
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
     runs-on: ubuntu-latest
     steps:
@@ -73,13 +99,38 @@ jobs:
     - name: Set up Python 3.8
       uses: actions/setup-python@v1
       with:
-        python-version: 3.8
+        python-version: "3.8"
     - name: Build package
       run: |
-        pip install wheel
-        python setup.py sdist bdist_wheel
+        pip install build
+        python -m build
     - name: Publish
       uses: pypa/gh-action-pypi-publish@v1.3.1
       with:
         user: __token__
         password: ${{ secrets.PYPI_KEY }}
+
+  publish-docutils:
+
+    name: Publish myst-docutils to PyPi
+    needs: [publish]
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout source
+      uses: actions/checkout@v2
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v1
+      with:
+        python-version: "3.8"
+    - name: Modify setup
+      run: python .github/workflows/docutils_setup.py setup.cfg README.md
+    - name: Build package
+      run: |
+        pip install build
+        python -m build
+    - name: Publish
+      uses: pypa/gh-action-pypi-publish@v1.3.1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_KEY_DOCUTILS }}