Skip to content

Commit

Permalink
馃И Add testing of document builds in other formats (#665)
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrisjsewell
chrisjsewell committed Jan 5, 2023
1 parent 2a206a8 commit 23ae135
Show file tree
Hide file tree
Showing 4 changed files with 162 additions and 76 deletions.
76 changes: 76 additions & 0 deletions .github/workflows/test-formats.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
name: build-doc-formats

on:
push:
branches: [master]
pull_request:

jobs:

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-builds-pdf:

name: Documentation builds
runs-on: ubuntu-latest

strategy:
fail-fast: false
matrix:
format: ["latex"]

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 }}
- name: Make PDF
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
142 changes: 79 additions & 63 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
from datetime import date

from sphinx.application import Sphinx
from sphinx.transforms.post_transforms import SphinxPostTransform

from myst_parser import __version__

Expand Down Expand Up @@ -44,12 +45,66 @@
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

suppress_warnings = ["myst.strikethrough"]

# -- Options for HTML output -------------------------------------------------
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 settings ---------------------------------------------------

autodoc_member_order = "bysource"
nitpicky = True
nitpick_ignore = [
("py:class", "docutils.nodes.document"),
("py:class", "docutils.nodes.docinfo"),
("py:class", "docutils.nodes.Element"),
("py:class", "docutils.nodes.Node"),
("py:class", "docutils.nodes.field_list"),
("py:class", "docutils.nodes.problematic"),
("py:class", "docutils.nodes.pending"),
("py:class", "docutils.nodes.system_message"),
("py:class", "docutils.statemachine.StringList"),
("py:class", "docutils.parsers.rst.directives.misc.Include"),
("py:class", "docutils.parsers.rst.Parser"),
("py:class", "docutils.utils.Reporter"),
("py:class", "nodes.Element"),
("py:class", "nodes.Node"),
("py:class", "nodes.system_message"),
("py:class", "Directive"),
("py:class", "Include"),
("py:class", "StringList"),
("py:class", "DocutilsRenderer"),
("py:class", "MockStateMachine"),
]

# -- MyST settings ---------------------------------------------------

myst_enable_extensions = [
"dollarmath",
"amsmath",
"deflist",
"fieldlist",
"html_admonition",
"html_image",
"colon_fence",
"smartquotes",
"replacements",
"linkify",
"strikethrough",
"substitution",
"tasklist",
"attrs_inline",
]
myst_number_code_blocks = ["typescript"]
myst_heading_anchors = 2
myst_footnote_transition = True
myst_dmath_double_inline = True

# -- HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_book_theme"
html_logo = "_static/logo-wide.svg"
html_favicon = "_static/logo-square.svg"
Expand All @@ -76,27 +131,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_inline",
]
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",
Expand All @@ -112,47 +146,28 @@
"explain/index.md": "develop/background.md",
}

suppress_warnings = ["myst.strikethrough"]
# -- 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),
}
# -- Local Sphinx extensions -------------------------------------------------

# 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"
nitpicky = True
nitpick_ignore = [
("py:class", "docutils.nodes.document"),
("py:class", "docutils.nodes.docinfo"),
("py:class", "docutils.nodes.Element"),
("py:class", "docutils.nodes.Node"),
("py:class", "docutils.nodes.field_list"),
("py:class", "docutils.nodes.problematic"),
("py:class", "docutils.nodes.pending"),
("py:class", "docutils.nodes.system_message"),
("py:class", "docutils.statemachine.StringList"),
("py:class", "docutils.parsers.rst.directives.misc.Include"),
("py:class", "docutils.parsers.rst.Parser"),
("py:class", "docutils.utils.Reporter"),
("py:class", "nodes.Element"),
("py:class", "nodes.Node"),
("py:class", "nodes.system_message"),
("py:class", "Directive"),
("py:class", "Include"),
("py:class", "StringList"),
("py:class", "DocutilsRenderer"),
("py:class", "MockStateMachine"),
]

class StripUnsupportedLatex(SphinxPostTransform):
"""Remove unsupported nodes from the doctree."""

default_priority = 900

def run(self):
if not self.app.builder.format == "latex":
return
from docutils import nodes

for node in self.document.findall():
if node.tagname == "image" and node["uri"].endswith(".svg"):
node.parent.replace(node, nodes.inline("", "Removed SVG image"))
if node.tagname == "mermaid":
node.parent.replace(node, nodes.inline("", "Removed Mermaid diagram"))


def setup(app: Sphinx):
Expand All @@ -169,3 +184,4 @@ def setup(app: Sphinx):
app.add_directive("docutils-cli-help", DocutilsCliHelpDirective)
app.add_directive("doc-directive", DirectiveDoc)
app.add_directive("myst-warnings", MystWarningsDirective)
app.add_post_transform(StripUnsupportedLatex)
18 changes: 6 additions & 12 deletions docs/syntax/optional.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,30 +138,24 @@ For example:

```latex
$$
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}
y & = ax^2 + bx + c \\
f(x) & = x^2 + 2xy + y^2
$$
```

becomes

$$
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}
y & = ax^2 + bx + c \\
f(x) & = x^2 + 2xy + y^2
$$

This is equivalent to the following directive:

````md
```{math}
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}
y & = ax^2 + bx + c \\
f(x) & = x^2 + 2xy + y^2
```
````

Expand Down
2 changes: 1 addition & 1 deletion tox.ini
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ whitelist_externals =
rm
echo
commands =
clean: rm -rf docs/_build
clean: rm -rf docs/_build/{posargs:html}
sphinx-build -nW --keep-going -b {posargs:html} docs/ docs/_build/{posargs:html}
commands_post = echo "open file://{toxinidir}/docs/_build/{posargs:html}/index.html"

Expand Down

0 comments on commit 23ae135

Please sign in to comment.