executablebooks · chrisjsewell · Aug 27, 2022 · Aug 31, 2022 · Sep 2, 2022 · Sep 2, 2022
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -25,7 +25,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.9", "3.10"]
         sphinx: [">=5,<6"]
         os: [ubuntu-latest]
         include:
@@ -103,10 +103,73 @@ jobs:
     - name: Run docutils CLI
       run: echo "test" | myst-docutils-html
 
+  doc-builds:
+
+    name: Documentation builds
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        format: ["man", "text"]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[linkify,rtd]
+    - name: Build docs
+      run: |
+        sphinx-build -nW --keep-going -b ${{ matrix.format }} docs/ docs/_build/${{ matrix.format }}
+
+  doc-build-pdf:
+
+    name: Documentation PDF build
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[linkify,rtd]
+    - name: Build docs
+      run: |
+        sphinx-build -nW --keep-going -b latex docs/ docs/_build/latex
+
+    - name: Run PDF build
+      uses: xu-cheng/latex-action@v2
+      with:
+        working_directory: docs/_build/latex
+        root_file: "mystparser.tex"
+        # https://github.com/marketplace/actions/github-action-for-latex#it-fails-due-to-xindy-cannot-be-found
+        pre_compile: |
+          ln -sf /opt/texlive/texdir/texmf-dist/scripts/xindy/xindy.pl /opt/texlive/texdir/bin/x86_64-linuxmusl/xindy
+          ln -sf /opt/texlive/texdir/texmf-dist/scripts/xindy/texindy.pl /opt/texlive/texdir/bin/x86_64-linuxmusl/texindy
+          wget https://sourceforge.net/projects/xindy/files/xindy-source-components/2.4/xindy-kernel-3.0.tar.gz
+          tar xf xindy-kernel-3.0.tar.gz
+          cd xindy-kernel-3.0/src
+          apk add make
+          apk add clisp --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community
+          make
+          cp -f xindy.mem /opt/texlive/texdir/bin/x86_64-linuxmusl/
+          cd ../../
+      env:
+        XINDYOPTS: -L english -C utf8  -M sphinx.xdy
+
   publish:
 
     name: Publish myst-parser to PyPi
-    needs: [pre-commit, tests, check-myst-docutils]
+    needs: [pre-commit, tests, check-myst-docutils, doc-builds]
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
     runs-on: ubuntu-latest
     steps:

diff --git a/.gitignore b/.gitignore
@@ -133,3 +133,4 @@ _archive/
 
 .vscode/
 .DS_Store
+TODO.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -100,7 +100,7 @@ In addition, configuration to more finely tune this behaviour has been added.
 - `myst_url_schemes=("http", "https")`, sets what URL schemes are treated as (1)
 - `myst_ref_domains=("std", "py")`, sets what Sphinx reference domains are checked, when handling (3)
 
-See [Markdown Links and Referencing](docs/syntax/syntax.md#markdown-links-and-referencing) for more information.
+See [Markdown Links and Referencing](docs/syntax/syntax.md#links-and-referencing) for more information.
 
 ### ‼️ Dollarmath is now disabled by default
 
@@ -363,7 +363,7 @@ In particular for users, this update alters the parsing of tables to be consiste
 
 ### New Features ✨
 
-- **Task lists** utilise the [markdown-it-py tasklists plugin](markdown_it:md/plugins), and are applied to Markdown list items starting with `[ ]` or `[x]`.
+- **Task lists** utilise the [markdown-it-py tasklists plugin](myst:markdown_it#md/plugins), and are applied to Markdown list items starting with `[ ]` or `[x]`.
 
   ```markdown
   - [ ] An item that needs doing
@@ -437,7 +437,7 @@ A warning (of type `myst.nested_header`) is now emitted when this occurs.
 - ✨ NEW: Add warning types `myst.subtype`:
   All parsing warnings are assigned a type/subtype, and also the messages are appended with them.
   These warning types can be suppressed with the sphinx `suppress_warnings` config option.
-  See [How-to suppress warnings](howto/warnings) for more information.
+  See [How-to suppress warnings](#myst-warnings) for more information.
 
 ## 0.13.3 - 2021-01-20
 
@@ -596,7 +596,7 @@ I’m an inline image: <img src="img/fun-fish.png" height="20px">
 ## 0.12.7 - 2020-08-31
 
 ✨ NEW: Want to include your README.md in the documentation?
-: See [including a file from outside the docs folder](howto/include-readme).
+: See [including a file from outside the docs folder](#howto/include-readme).
 
 (👌 added `relative-docs` option in 0.12.8)
 

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -1,19 +1,7 @@
 /** Add a counter before subsections **/
 h1 {
-    counter-reset: subsection;
     text-decoration: underline;
 }
-h2 {
-    counter-reset: subsubsection;
-}
-h2::before {
-    counter-increment: subsection;
-    content: counter(subsection) ". ";
-}
-h3::before {
-    counter-increment: subsubsection;
-    content: counter(subsection) "." counter(subsubsection) ". ";
-}
 
 /** No icon for admonitions with no-icon class */
 .admonition > .admonition-title, div.admonition.no-icon > .admonition-title::before {

diff --git a/docs/api/reference.rst b/docs/api/reference.rst
@@ -56,7 +56,6 @@ Sphinx
 
 .. autoclass:: myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer
     :special-members: __output__
-    :members: render_internal_link, render_math_block_label
     :undoc-members:
     :member-order: alphabetical
     :show-inheritance:

diff --git a/docs/conf.py b/docs/conf.py
@@ -44,6 +44,40 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.7", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "markdown_it": ("https://markdown-it-py.readthedocs.io/en/latest", None),
+}
+
+autodoc_member_order = "bysource"
+
+# -- Parsing Configuration ---------------------------------------------------
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "colon_fence",
+    "smartquotes",
+    "replacements",
+    "linkify",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+    "attrs_image",
+]
+myst_number_code_blocks = ["typescript"]
+myst_heading_anchors = 2
+myst_link_placeholders = True
+myst_footnote_transition = True
+myst_dmath_double_inline = True
+numfig = True
+numfig_secnum_depth = 2
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -76,27 +110,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-myst_enable_extensions = [
-    "dollarmath",
-    "amsmath",
-    "deflist",
-    "fieldlist",
-    "html_admonition",
-    "html_image",
-    "colon_fence",
-    "smartquotes",
-    "replacements",
-    "linkify",
-    "strikethrough",
-    "substitution",
-    "tasklist",
-    "attrs_image",
-]
-myst_number_code_blocks = ["typescript"]
-myst_heading_anchors = 2
-myst_footnote_transition = True
-myst_dmath_double_inline = True
-
 rediraffe_redirects = {
     "using/intro.md": "sphinx/intro.md",
     "sphinx/intro.md": "intro.md",
@@ -112,24 +125,13 @@
     "explain/index.md": "develop/background.md",
 }
 
-suppress_warnings = ["myst.strikethrough"]
+# -- Options for LaTeX output -------------------------------------------------
 
+latex_engine = "xelatex"
 
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.7", None),
-    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
-    "markdown_it": ("https://markdown-it-py.readthedocs.io/en/latest", None),
-}
+# -- Options for Warnings -------------------------------------------------
 
-# autodoc_default_options = {
-#     "show-inheritance": True,
-#     "special-members": "__init__, __enter__, __exit__",
-#     "members": True,
-#     # 'exclude-members': '',
-#     "undoc-members": True,
-#     # 'inherited-members': True
-# }
-autodoc_member_order = "bysource"
+suppress_warnings = ["myst.strikethrough", "myst.strip", "myst.xref_not_explicit"]
 nitpicky = True
 nitpick_ignore = [
     ("py:class", "docutils.nodes.document"),
@@ -161,9 +163,15 @@ def setup(app: Sphinx):
         DirectiveDoc,
         DocutilsCliHelpDirective,
         MystConfigDirective,
+        MystWarningsDirective,
+        StripMermaid,
+        StripSVGImages,
     )
 
     app.add_css_file("custom.css")
     app.add_directive("myst-config", MystConfigDirective)
+    app.add_directive("myst-warnings", MystWarningsDirective)
     app.add_directive("docutils-cli-help", DocutilsCliHelpDirective)
     app.add_directive("doc-directive", DirectiveDoc)
+    app.add_post_transform(StripMermaid)
+    app.add_post_transform(StripSVGImages)
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -38,7 +38,7 @@ Configuration specific to syntax extensions:
 ```
 
 The following configuration variables are available at the document level.
-These can be set in the document [front matter](syntax/frontmatter), under the `myst` key, e.g.
+These can be set in the document [front matter](#syntax/frontmatter), under the `myst` key, e.g.
 
 ```yaml
 ---
@@ -64,28 +64,28 @@ Configuration specific to syntax extensions:
 
 ## List of syntax extensions
 
-Full details in the [](syntax/extensions) section.
+Full details in the <project:#syntax/extensions> section.
 
 amsmath
 : enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations
 
 colon_fence
-: Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
+: Enable code fences using `:::` delimiters, [see here](#syntax/colon_fence) for details
 
 deflist
-: Enable definition lists, [see here](syntax/definition-lists) for details
+: Enable definition lists, [see here](#syntax/definition-lists) for details
 
 dollarmath
 : Enable parsing of dollar `$` and `$$` encapsulated math
 
 fieldlist
-: Enable field lists, [see here](syntax/fieldlists) for details
+: Enable field lists, [see here](#syntax/fieldlists) for details
 
 html_admonition
-: Convert `<div class="admonition">` elements to sphinx admonition nodes, see the [HTML admonition syntax](syntax/html-admonition) for details
+: Convert `<div class="admonition">` elements to sphinx admonition nodes, see the [HTML admonition syntax](#syntax/html-admonition) for details
 
 html_image
-: Convert HTML `<img>` elements to sphinx image nodes, [see here](syntax/images) for details
+: Convert HTML `<img>` elements to sphinx image nodes, [see here](#syntax/images) for details
 
 linkify
 : Automatically identify "bare" web URLs and add hyperlinks
@@ -97,10 +97,30 @@ smartquotes
 : Automatically convert standard quotations to their opening/closing variants
 
 strikethrough
-: Enable strikethrough syntax, [see here](syntax/strikethrough) for details
+: Enable strikethrough syntax, [see here](#syntax/strikethrough) for details
 
 substitution
-: Substitute keys, [see here](syntax/substitutions) for details
+: Substitute keys, [see here](#syntax/substitutions) for details
 
 tasklist
-: Add check-boxes to the start of list items, [see here](syntax/tasklists) for details
+: Add check-boxes to the start of list items, [see here](#syntax/tasklists) for details
+
+(myst-warnings)=
+## Build Warnings
+
+Below lists the MyST specific warnings that may be emitted during the build process. These will be prepended to the end of the warning message, e.g.
+
+```
+WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
+```
+
+**In general, if your build logs any warnings, you should either fix them or [raise an Issue](https://github.com/executablebooks/MyST-Parser/issues/new/choose) if you think the warning is erroneous.**
+
+However, in some circumstances if you wish to suppress the warning you can use the [`suppress_warnings`](myst:sphinx#suppress_warnings) configuration option, e.g.
+
+```python
+suppress_warnings = ["myst.header"]
+```
+
+```{myst-warnings}
+```
diff --git a/docs/develop/background.md b/docs/develop/background.md
@@ -11,7 +11,7 @@ but there is no community standard around various syntactic choices for these fe
 Sphinx is a documentation generation framework written in Python. It heavily-utilizes
 reStructuredText syntax, which is another markup language for writing documents. In
 particular, Sphinx defines two extension points that are extremely useful:
-**{ref}`in-line roles<sphinx:rst-roles-alt>`** and **{ref}`block-level directives <sphinx:rst-directives>`**.
+[**in-line roles**](myst:sphinx#rst-roles-alt) and [**block-level directives**](myst:sphinx#rst-directives).
 
 **This project is an attempt at combining the simplicity and readability of Markdown
 with the power and flexibility of reStructuredText and the Sphinx platform.** It

diff --git a/docs/docutils.md b/docs/docutils.md
@@ -28,13 +28,17 @@ $ echo "Hello World" | myst-docutils-html
 $ myst-docutils-html hello-world.md
 ```
 
-The commands are based on the [Docutils Front-End Tools](https://docutils.sourceforge.io/docs/user/tools.html), and so follow the same argument and options structure, included many of the MyST specific options detailed in [](sphinx/config-options).
+The commands are based on the [Docutils Front-End Tools](https://docutils.sourceforge.io/docs/user/tools.html), and so follow the same argument and options structure, included many of the MyST specific options detailed in <project:#sphinx/config-options>.
 
 :::{dropdown}  Shared Docutils CLI Options
 ```{docutils-cli-help}
 ```
 :::
 
+:::{versionadded} 0.19.0
+`myst-suppress-warnings` replicates the functionality of  [sphinx's `suppress_warnings`](myst:sphinx#suppress_warnings) for `myst.` warnings in the `docutils` CLI.
+:::
+
 The CLI commands can also utilise the [`docutils.conf` configuration file](https://docutils.sourceforge.io/docs/user/config.html) to configure the behaviour of the CLI commands. For example:
 
 ```