From 12ac00c220db6ede5beae24e74599e1b4146c3b4 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Tue, 2 May 2023 10:25:15 -0700 Subject: [PATCH] fix #250 (#254) * add myst-example directive * use myst-example directive in the MyST example topology doc --- docs/conf.py | 4 - docs/myst_typography.md | 261 +++--------------------------- sphinx_immaterial/theme_result.py | 9 +- 3 files changed, 29 insertions(+), 245 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a1b67c91d..19dd7290e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -533,10 +533,6 @@ 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/myst_typography.md b/docs/myst_typography.md index 20d7695b1..295323c28 100644 --- a/docs/myst_typography.md +++ b/docs/myst_typography.md @@ -20,7 +20,7 @@ Markdown syntax denotes headers starting with between 1 to 6 #.
-```{code-block} myst +```{code-block} md ### Heading Level 3 ``` @@ -35,20 +35,11 @@ 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 +```{myst-example} > {.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). @@ -62,27 +53,18 @@ 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 +```{myst-example} {.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. - -
- ## 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 +```{code-block} md * * * ``` @@ -97,96 +79,48 @@ You can create a thematic break, to break content between themes, using three or Standard inline formatting including bold, italic, code, as well as escaped symbols and line breaks: -
- -```{code-block} myst +```{myst-example} **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 +```{myst-example} ~~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 +```{myst-example} 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 +```{myst-example} 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 +```{myst-example} 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 +```{myst-example} - Lists can start with `-` or `*` * My other, nested * bullet point list! @@ -195,17 +129,6 @@ These lists can be nested using two spaces at the start of the line. 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. @@ -216,9 +139,7 @@ The exception is the first number, which if it is not `1.` this will change the Using the [attrs_block](#syntax/attributes/block) extension, you can also specify a alternative numbering styles: -
- -```{code-block} myst +```{myst-example} {style=lower-alpha} 1. a 2. b @@ -235,104 +156,47 @@ you can also specify a alternative numbering styles: 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 +```{myst-example} - [ ] 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 +```{myst-example} 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 +```{myst-example} > 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 +```{myst-example} {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 +```{myst-example} Term 1 : Definition @@ -345,26 +209,10 @@ Term 2 ``` -
- -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 +```{myst-example} {.glossary} my term : Definition of the term @@ -372,24 +220,12 @@ my 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 +```{myst-example} :param arg1: A description of arg1 :param arg2: A longer description, @@ -399,17 +235,6 @@ you can create field lists, which are useful in source code documentation (see [ :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 @@ -417,7 +242,7 @@ prevent the line from being parsed into the output document. For example, this won't be parsed into the document: -```{code-block} myst +```{code-block} md % my comment ``` @@ -429,22 +254,11 @@ 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 +```{myst-example} a line % a comment another line ``` - -
- -a line -% a comment -another line - -
- ```` ## Footnotes @@ -458,9 +272,7 @@ Their labels **start with `^`** and can then be any alphanumeric string (no spac 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 +```{myst-example} - This is a manually-numbered footnote reference.[^3] - This is an auto-numbered footnote reference.[^myref] @@ -468,22 +280,10 @@ Note that un-referenced footnote definitions will not be displayed. [^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 +```{myst-example} A longer footnote definition.[^mylongdef] [^mylongdef]: This is the _**footnote definition**_. @@ -498,23 +298,6 @@ 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, diff --git a/sphinx_immaterial/theme_result.py b/sphinx_immaterial/theme_result.py index 6290ec3b8..bc5c9b404 100644 --- a/sphinx_immaterial/theme_result.py +++ b/sphinx_immaterial/theme_result.py @@ -1,6 +1,8 @@ """A directive designed to reduce example snippets duplication.""" +from pathlib import PurePath from docutils.parsers.rst import directives from docutils import nodes +from sphinx.application import Sphinx from sphinx.util.docutils import SphinxDirective from sphinx.directives.code import container_wrapper @@ -25,7 +27,9 @@ def run(self): ) code = "\n".join(self.content) literal_node: nodes.Element = nodes.literal_block(code, code) - literal_node["language"] = "rst" + src_file: str = self.state.document.attributes["source"] + suffix = PurePath(src_file).suffix.lstrip(".") + literal_node["language"] = suffix if self.arguments: literal_node = container_wrapper(self, literal_node, self.arguments[0]) container_node += literal_node @@ -49,8 +53,9 @@ def run(self): return [container_node] -def setup(app): +def setup(app: Sphinx): app.add_directive("rst-example", ResultsDirective) + app.add_directive("myst-example", ResultsDirective) return { "parallel_read_safe": True, "parallel_write_safe": True,