From a196599c6e3719d863daec4f46224ebe6b1b053e Mon Sep 17 00:00:00 2001 From: John Hennig Date: Wed, 31 Mar 2021 03:02:58 +0200 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9A=20DOCS:=20Warn=20that=20autodo?= =?UTF-8?q?c=20expects=20rST=20docstrings,=20not=20Markdown.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/using/howto.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/using/howto.md b/docs/using/howto.md index 56b6ee5e..48e9c8a6 100644 --- a/docs/using/howto.md +++ b/docs/using/howto.md @@ -80,8 +80,9 @@ If you encounter any issues with this feature, please don't hesitate to report i (howto/autodoc)= ## Use `sphinx.ext.autodoc` in Markdown files -The [sphinx.ext.autodoc](sphinx:sphinx.ext.autodoc) is currently hard-coded to write rST, and so can not be used as a conventional MyST directive. -Instead the special [eval-rst directive](syntax/directives/parsing) can be used to "wrap" the autodoc directives: +The [Sphinx extension `autodoc`](sphinx:sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to output reStructuredText. +It therefore does not blend in well with MyST, which expects Markdown as input. +However, the special [`eval-rst` directive](syntax/directives/parsing) can be used to "wrap" `autodoc` directives: ````md ```{eval-rst} @@ -102,6 +103,11 @@ As with other objects in MyST, this can then be referenced: - Using the role `` {py:class}`myst_parser.mocking.MockRSTParser` ``: {py:class}`myst_parser.mocking.MockRSTParser` - Using the Markdown syntax `[MockRSTParser](myst_parser.mocking.MockRSTParser)`: [MockRSTParser](myst_parser.mocking.MockRSTParser) +```{warning} +This expects docstrings to be written in reStructuredText. +We hope to support Markdown in the future, see [GitHub issue #228](https://github.com/executablebooks/MyST-Parser/issues/228). +``` + ## Show backticks inside raw markdown blocks If you'd like to show backticks inside of your markdown, you can do so by nesting them From 334fb09aebedc347817b4a32a2f93c2360a36ba1 Mon Sep 17 00:00:00 2001 From: John Hennig Date: Wed, 31 Mar 2021 04:16:05 +0200 Subject: [PATCH 2/3] Update docs/using/howto.md Co-authored-by: Chris Sewell --- docs/using/howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/howto.md b/docs/using/howto.md index 48e9c8a6..a21490e8 100644 --- a/docs/using/howto.md +++ b/docs/using/howto.md @@ -80,7 +80,7 @@ If you encounter any issues with this feature, please don't hesitate to report i (howto/autodoc)= ## Use `sphinx.ext.autodoc` in Markdown files -The [Sphinx extension `autodoc`](sphinx:sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to output reStructuredText. +The [Sphinx extension `autodoc`](sphinx:sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to parse reStructuredText. It therefore does not blend in well with MyST, which expects Markdown as input. However, the special [`eval-rst` directive](syntax/directives/parsing) can be used to "wrap" `autodoc` directives: From 3e723953c3b1b18949c2fcac33a794f779baed43 Mon Sep 17 00:00:00 2001 From: John Hennig Date: Wed, 31 Mar 2021 04:16:14 +0200 Subject: [PATCH 3/3] Update docs/using/howto.md Co-authored-by: Chris Sewell --- docs/using/howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/howto.md b/docs/using/howto.md index a21490e8..806c344e 100644 --- a/docs/using/howto.md +++ b/docs/using/howto.md @@ -81,7 +81,7 @@ If you encounter any issues with this feature, please don't hesitate to report i ## Use `sphinx.ext.autodoc` in Markdown files The [Sphinx extension `autodoc`](sphinx:sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to parse reStructuredText. -It therefore does not blend in well with MyST, which expects Markdown as input. +It is therefore incompatible with MyST's Markdown parser. However, the special [`eval-rst` directive](syntax/directives/parsing) can be used to "wrap" `autodoc` directives: ````md