From c62da57fbdac056cda1947b21601e6b129c1cff6 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Thu, 27 Apr 2023 17:12:29 -0700 Subject: [PATCH] resolve #162 The MyST example doc is a bit raw, but it is meant to encourage further contributions by providing a foundation to build on. --- docs/conf.py | 28 +++ docs/index.rst | 1 + docs/myst.md | 529 ++++++++++++++++++++++++++++++++++++++++++ docs/requirements.txt | 1 + 4 files changed, 559 insertions(+) create mode 100644 docs/myst.md diff --git a/docs/conf.py b/docs/conf.py index 20893191e..a1b67c91d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,11 +60,13 @@ "sphinx_immaterial.apidoc.cpp.apigen", "sphinx_immaterial.graphviz", "sphinx_jinja", + "myst_parser", ] intersphinx_mapping = { "python": ("https://docs.python.org/3", None), "sphinx_docs": ("https://www.sphinx-doc.org/en/master", None), + "MyST parser docs": ("https://myst-parser.readthedocs.io/en/latest", None), } # The reST default role (used for this markup: `text`) to use for all @@ -440,6 +442,28 @@ graphviz_ignore_incorrect_font_metrics = True +# MyST parser config options +myst_enable_extensions = [ + "deflist", + "fieldlist", + "smartquotes", + "replacements", + "strikethrough", + "substitution", + "tasklist", + "attrs_inline", + "attrs_block", +] + +myst_enable_checkboxes = True +myst_substitutions = { + "role": "[role](#syntax/roles)", +} + +# Myst parser's strikethrough plugin seems to think that sphinx-immaterial doesn't use +# HTML output (probably due to the custom translator mixin used). +suppress_warnings = ["myst.strikethrough"] + def _validate_parallel_build(app): # Verifies that all of the extensions defined by this theme support parallel @@ -509,6 +533,10 @@ def _parse_confval_signature( def setup(app): + from myst_parser._docs import MystLexer + + app.add_lexer("myst", MystLexer) + app.add_object_type( "confval", "confval", diff --git a/docs/index.rst b/docs/index.rst index 29a8be305..588bf515d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -141,3 +141,4 @@ or ``theme.conf`` for more details. rst_basics rst-cheatsheet/rst-cheatsheet additional_samples + myst diff --git a/docs/myst.md b/docs/myst.md new file mode 100644 index 000000000..3e6285400 --- /dev/null +++ b/docs/myst.md @@ -0,0 +1,529 @@ + + + + + +# MyST MarkDown Typography + +MyST is a strict superset of the [CommonMark syntax specification](https://spec.commonmark.org/). +It adds features focussed on scientific and technical documentation authoring, as detailed below. + +## Headings + +Markdown syntax denotes headers starting with between 1 to 6 #. + +
+ +```{code-block} myst +### Heading Level 3 +``` + +
+ +### Heading Level 3 + +
+ +Note, that headings that are not at the root level of the document +will not be included in the table of contents. +Using the [attrs_block](#syntax/attributes/block) extension, +you can also add classes to headings + +
+ +```{code-block} myst +> {.bg-primary} +> ### Paragraph heading +``` + +
+ +> {.bg-primary} +> ### Paragraph heading + +
+ +```{seealso} +To structure single and multiple documents into table of contents, see the [organizing content section](#organising-content). + +To reference a heading in your text, see the [cross-referencing section](#syntax/referencing). +``` + +## Paragraphs + +Paragraphs are block of text separated by a blank line. + +Using the [attrs_block](#syntax/attributes/block) extension, +you can also add classes to paragraphs: + +
+ +```{code-block} myst +{.bg-primary} +Here is a paragraph with a class to control its formatting. +``` + +
+ +{.bg-primary} +Here is a paragraph with a class to control its formatting. + +
+ +(syntax/blockbreaks)= + +## Thematic breaks + +You can create a thematic break, to break content between themes, using three or more `*`, `-`, or `_` characters on a line by themselves. + +
+ +```{code-block} myst + +* * * +``` + +
+ +* * * + +
+ +## Inline Text Formatting + +Standard inline formatting including bold, italic, code, as well as escaped symbols and line breaks: + +
+ +```{code-block} myst +**strong**, _emphasis_, `literal text`, \*escaped symbols\* +``` + +
+ +**strong**, _emphasis_, `literal text`, \*escaped symbols\* + +
+ +The [strikethrough](syntax/strikethrough) extension allows you to add strike-through text: + +
+ +```{code-block} text +~~strikethrough with *emphasis*~~ +``` + +
+ +```{only} html +~~strikethrough with *emphasis*~~ +``` + +
+ +The [smartquotes](syntax/smartquotes) and [replacements](syntax/replacements) extensions can improve the typography of common symbols: + +
+ +```{code-block} myst +Smart-quotes 'single quotes' and "double quotes". + ++-, --, ---, ... and other replacements. +``` + +
+ +Smart-quotes 'single quotes' and "double quotes". + ++-, --, ---, ... and other replacements. + +
+ +Using the [attrs_inline](syntax/attributes/inline) extension, +you can also add classes to inline text spans: + +
+ +```{code-block} myst +A paragraph with a span of [text with attributes]{.bg-primary} +``` + +
+ +A paragraph with a span of [text with attributes]{.bg-primary} + +
+ +## Line Breaks + +To put a line break, without a paragraph, use a `\` followed by a new line. This corresponds to a `
` in HTML and `\\` in LaTeX. + +
+ +```{code-block} myst +Fleas \ +Adam \ +Had 'em. +``` + +
+ +Fleas \ +Adam \ +Had 'em. + +
+ +## Bullet points and numbered lists + +You can use bullet points and numbered lists as you would in standard Markdown. +Starting a line with either a `-` or `*` for a bullet point, and `1.` for numbered lists. +These lists can be nested using two spaces at the start of the line. + +
+ +```{code-block} myst +- Lists can start with `-` or `*` + * My other, nested + * bullet point list! + +1. My numbered list +2. has two points +``` + +
+ +- Lists can start with `-` or `*` + * My other, nested + * bullet point list! + +1. My numbered list +2. has two points + +
+ +For numbered lists, you can start following lines with any number, meaning they don't have to be in numerical order, and this will not change the rendered output. +The exception is the first number, which if it is not `1.` this will change the start number of the list. + +````{tip} +:title: Alternate numbering styles +:collapsible: + +Using the [attrs_block](#syntax/attributes/block) extension, +you can also specify a alternative numbering styles: + +
+ +```{code-block} myst +{style=lower-alpha} +1. a +2. b + +{style=upper-alpha} +1. a +2. b + +{style=lower-roman} +1. a +2. b + +{style=upper-roman} +1. a +2. b +``` + +
+ +{style=lower-alpha} +1. a +2. b + +{style=upper-alpha} +1. a +2. b + +{style=lower-roman} +1. a +2. b + +{style=upper-roman} +1. a +2. b + +
+ +```` + +Using the [tasklist](syntax/tasklists) extension, +you can also create task lists: + +
+ +```{code-block} myst +- [ ] An item that needs doing +- [x] An item that is complete +``` + +
+ +- [ ] An item that needs doing +- [x] An item that is complete + +
+ +## Subscript & Superscript + +For inline typography for subscript and superscript formatting, +the `sub` and `sup` {{role}}, can be used respectively. + +
+ +```{code-block} myst +H{sub}`2`O, and 4{sup}`th` of July +``` + +
+ +H{sub}`2`O, and 4{sup}`th` of July + +
+ +## Quotations + +Quotations are controlled with standard Markdown syntax, by inserting a caret (>) symbol in front of one or more lines of text. + +
+ +```{code-block} myst +> We know what we are, but know not what we may be. +``` + +
+ +> We know what we are, but know not what we may be. + +
+ +Using the [attrs_block](#syntax/attributes/block) extension, +you can also add an `attribution` attribute to a block quote: + +
+ +```{code-block} myst +{attribution="Hamlet act 4, Scene 5"} +> We know what we are, but know not what we may be. +``` + +
+ +{attribution="Hamlet act 4, Scene 5"} +> We know what we are, but know not what we may be. + +
+ +## Definition lists and glossaries + +Using the [definition lists](syntax/definition-lists) extension, +you can define terms in your documentation, using the syntax: + +
+ +```{code-block} myst +Term 1 +: Definition + +Term 2 +: Longer definition + + With multiple paragraphs + + - And bullet points + +``` + +
+ +Term 1 +: Definition + +Term 2 +: Longer definition + + With multiple paragraphs + + - And bullet points + +
+ +Using the [attrs_block](#syntax/attributes/block) extension, +you can also add a `glossary` class to a definition list, that will allow you to reference terms in your text using the [`term` role](syntax/roles): + +
+ +```{code-block} myst +{.glossary} +my term +: Definition of the term + +{term}`my term` +``` + +
+ +{.glossary} +my term +: Definition of the term + +{term}`my term` + +
+ +## Field lists + +Using the [field lists](syntax/fieldlists) extension, +you can create field lists, which are useful in source code documentation (see [Sphinx docstrings](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists)): + +
+ +```{code-block} myst + +:param arg1: A description of arg1 +:param arg2: A longer description, + with multiple lines. + + - And bullet points +:return: A description of the return value +``` + +
+ +:param arg1: A description of arg1 +:param arg2: A longer description, + with multiple lines. + + - And bullet points +:return: A description of the return value + +
+ +## Comments + +You may add comments by putting the `%` character at the beginning of a line. This will +prevent the line from being parsed into the output document. + +For example, this won't be parsed into the document: + +```{code-block} myst +% my comment +``` + +````{warning} +:title: Comments split paragraphs +:collapsible: + +Since comments are a block-level entity, they will terminate the previous block. +In practical terms, this means that the following lines +will be broken up into two paragraphs, resulting in a new line between them: + +
+ +```{code-block} myst +a line +% a comment +another line +``` + +
+ +a line +% a comment +another line + +
+ +```` + +## Footnotes + +Footnotes use the [pandoc specification](https://pandoc.org/MANUAL.html#footnotes). +Their labels **start with `^`** and can then be any alphanumeric string (no spaces), which is case-insensitive. + +- If the label is an integer, then it will always use that integer for the rendered label (i.e. they are manually numbered). +- For any other labels, they will be auto-numbered in the order which they are referenced, skipping any manually numbered labels. + +All footnote definitions are collected, and displayed at the bottom of the page (in the order they are referenced). +Note that un-referenced footnote definitions will not be displayed. + +
+ +```{code-block} myst +- This is a manually-numbered footnote reference.[^3] +- This is an auto-numbered footnote reference.[^myref] + +[^myref]: This is an auto-numbered footnote definition. +[^3]: This is a manually-numbered footnote definition. +``` + +
+ +- This is a manually-numbered footnote reference.[^3] +- This is an auto-numbered footnote reference.[^myref] + +[^myref]: This is an auto-numbered footnote definition. +[^3]: This is a manually-numbered footnote definition. + +
+ +Any preceding text after a footnote definitions, which is +indented by four or more spaces, will also be included in the footnote definition, and the text is rendered as MyST Markdown, e.g. + +
+ +```{code-block} myst +A longer footnote definition.[^mylongdef] + +[^mylongdef]: This is the _**footnote definition**_. + + That continues for all indented lines + + - even other block elements + + Plus any preceding unindented lines, +that are not separated by a blank line + +This is not part of the footnote. +``` + +
+ +A longer footnote definition.[^mylongdef] + +[^mylongdef]: This is the _**footnote definition**_. + + That continues for all indented lines + + - even other block elements + + Plus any preceding unindented lines, +that are not separated by a blank line + +This is not part of the footnote. + +
+ +```{important} +Although footnote references can be used just fine within directives, e.g.[^myref], +it is recommended that footnote definitions are not set within directives, +unless they will only be referenced within that same directive: + +This is because, they may not be available to reference in text outside that particular directive. +``` + +By default, a transition line (with a `footnotes` class) will be placed before any footnotes. +This can be turned off by adding `myst_footnote_transition = False` to the config file. diff --git a/docs/requirements.txt b/docs/requirements.txt index 5620fcc4d..fa953b9db 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx-immaterial[json,clang-format,keys,cpp] sphinx-jinja +myst-parser