.github/workflows/docutils_setup.py

@@ -44,12 +44,12 @@ def modify_readme(content: str) -> str:
 if __name__ == "__main__":
     project_path = sys.argv[1]
     readme_path = sys.argv[2]
-    with open(project_path, "r") as f:
+    with open(project_path) as f:
         content = f.read()
     content = modify_toml(content)
     with open(project_path, "w") as f:
         f.write(content)
-    with open(readme_path, "r") as f:
+    with open(readme_path) as f:
         content = f.read()
     content = modify_readme(content)
     with open(readme_path, "w") as f:

.github/workflows/tests.yml

@@ -26,16 +26,15 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.7", "3.8", "3.9", "3.10"]
-        sphinx: [">=4,<5"]
+        sphinx: [">=5,<6"]
         os: [ubuntu-latest]
         include:
-          # fails because of: https://github.com/sphinx-doc/sphinx/issues/10291
-          # - os: ubuntu-latest
-          #   python-version: "3.8"
-          #   sphinx: ">=3,<4"
-          - os: windows-latest
-            python-version: "3.8"
-            sphinx: ">=4,<5"
+        - os: ubuntu-latest
+          python-version: "3.8"
+          sphinx: ">=4,<5"
+        - os: windows-latest
+          python-version: "3.8"
+          sphinx: ">=4,<5"
 
     runs-on: ${{ matrix.os }}
 
@@ -89,7 +88,7 @@ jobs:
     - name: Install dependencies
       run: |
         pip install .
-        pip install pytest~=6.2 pytest-param-files~=0.3.3 docutils==${{ matrix.docutils-version }}
+        pip install pytest~=6.2 pytest-param-files~=0.3.3 pygments docutils==${{ matrix.docutils-version }}
     - name: ensure sphinx is not installed
       run: |
         python -c "\
@@ -100,7 +99,7 @@ jobs:
         else:
             raise AssertionError()"
     - name: Run pytest for docutils-only tests
-      run: pytest tests/test_docutils.py tests/test_renderers/test_fixtures_docutils.py
+      run: pytest tests/test_docutils.py tests/test_renderers/test_fixtures_docutils.py tests/test_renderers/test_include_directive.py
     - name: Run docutils CLI
       run: echo "test" | myst-docutils-html
 

.pre-commit-config.yaml

@@ -19,6 +19,12 @@ repos:
     - id: end-of-file-fixer
     - id: trailing-whitespace
 
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v2.34.0
+    hooks:
+    - id: pyupgrade
+      args: [--py37-plus]
+
   - repo: https://github.com/PyCQA/isort
     rev: 5.10.1
     hooks:
@@ -39,12 +45,12 @@ repos:
         # - flake8-self~=0.2.2
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.942
+    rev: v0.961
     hooks:
     - id: mypy
       args: [--config-file=pyproject.toml]
       additional_dependencies:
-      - sphinx~=3.3
+      - sphinx~=5.0
       - markdown-it-py>=1.0.0,<3.0.0
       - mdit-py-plugins~=0.3.0
       files: >

.readthedocs.yml

@@ -1,7 +1,7 @@
 version: 2
 
 python:
-  version: 3
+  version: "3"
   install:
       - method: pip
         path: .

CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.18.0 - 2022-06-07
+
+Full Changelog: [v0.17.2...v0.18.0](https://github.com/executablebooks/MyST-Parser/compare/v0.17.2...v0.18.0)
+
+This release adds support for Sphinx v5 (dropping v3), restructures the code base into modules, and also restructures the documentation, to make it easier for developers/users to follow.
+
+It also introduces **document-level configuration**  *via* the Markdown top-matter, under the `myst` key.
+See the [Local configuration](docs/configuration.md) section for more information.
+
+### Breaking changes
+
+This should not be breaking, for general users of the sphinx extension (with `sphinx>3`),
+but will be for anyone directly using the Python API, mainly just requiring changes in import module paths.
+
+The `to_docutils`, `to_html`, `to_tokens` (from `myst_parser/main.py`) and `mock_sphinx_env`/`parse` (from `myst_parser.sphinx_renderer.py`) functions have been removed, since these were primarily for internal testing.
+Instead, for single page builds, users should use the docutils parser API/CLI (see [](docs/docutils.md)),
+and for testing, functionality has been moved to <https://github.com/chrisjsewell/sphinx-pytest>.
+
+The top-level `html_meta` and `substitutions` top-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the `myst` config, e.g.
+
+```yaml
+---
+html_meta:
+  "description lang=en": "metadata description"
+substitutions:
+  key1: I'm a **substitution**
+---
+```
+
+is replaced by:
+
+```yaml
+---
+myst:
+  html_meta:
+    "description lang=en": "metadata description"
+  substitutions:
+    key1: I'm a **substitution**
+---
+```
+
+### Key PRs
+
+- ♻️📚 Restructure code base and documentation (#566)
+- ⬆️ Drop Sphinx 3 and add Sphinx 5 support (#579)
+- 🐛 FIX: `parse_directive_text` when body followed by options (#580)
+- 🐛 FIX: floor table column widths to integers (#568), thanks to @Jean-Abou-Samra!
+
 ## 0.17.2 - 2022-04-17
 
 Full Changelog: [v0.17.1...v0.17.2](https://github.com/executablebooks/MyST-Parser/compare/v0.17.1...v0.17.2)

docs/_static/custom.css

@@ -1,11 +1,24 @@
-.bg-myst-one {
-    background-color: #52d16f3b;
+/** Add a counter before subsections **/
+h1 {
+    counter-reset: subsection;
+    text-decoration: underline;
 }
-
-.bg-myst-two {
-    background-color: #e7dd7b73;
+h2 {
+    counter-reset: subsubsection;
+}
+h2::before {
+    counter-increment: subsection;
+    content: counter(subsection) ". ";
+}
+h3::before {
+    counter-increment: subsubsection;
+    content: counter(subsection) "." counter(subsubsection) ". ";
 }
 
-.bg-myst-three {
-    background-color: #e7b07b96;
+/** No icon for admonitions with no-icon class */
+.admonition > .admonition-title, div.admonition.no-icon > .admonition-title::before {
+    content: "";
+}
+.admonition > .admonition-title, div.admonition.no-icon > .admonition-title {
+    padding-left: .6rem;
 }