Merge pull request #31 from OpenDataServices/fix-docs-myst-parser

Fix the docs to use myst-parser correctly, and fix markdown directive

CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [0.1.1] - 2021-05-18
+
+### Fixed
+
+- Fix the markdown directive, so it doesn't fail on anything that required sphinx (and not just docutils) formatting.
+
 ## [0.1.0] - 2021-05-11
 
 First release of project (was previously included by pip installing from a git commit).

docs/jsoninclude.md

@@ -2,7 +2,7 @@
 
 ## Standard JSON Include
 
-`````eval_rst
+`````{eval-rst}
 
 .. rst:directive:: jsoninclude
 
@@ -16,7 +16,7 @@
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude:: _static/example.json
                 :jsonpointer: /a/0/b
                 :expand: e
@@ -28,7 +28,7 @@
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude:: _static/example.json
                 :jsonpointer: /a/0/b
                 :exclude: e,g
@@ -38,7 +38,7 @@
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude:: _static/example.json
                 :jsonpointer: /a/0/b
                 :include_only: e,g
@@ -65,11 +65,11 @@ You need to add the files to a `_static` folder within your docs, and then add t
 
 The option `expand` can be used to control which lists are expanded initially. The option `title` can be used to give the json include a title; only one of consecutive includes will be shown, with a select box to switch:
 
-`````eval_rst
+`````{eval-rst}
 
 .. literal-and-parsed-markdown::
 
-    ```eval_rst
+    ```{eval-rst}
     .. jsoninclude:: _static/example.json
         :jsonpointer: 
         :title: collapsed
@@ -84,7 +84,7 @@ The option `expand` can be used to control which lists are expanded initially. T
 
 ## Flat JSON Include
 
-`````eval_rst
+`````{eval-rst}
 
 .. rst:directive:: jsoninclude-flat
 
@@ -98,7 +98,7 @@ The option `expand` can be used to control which lists are expanded initially. T
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude-flat:: _static/example.json
                 :jsonpointer: /a/0/b
             ```
@@ -107,7 +107,7 @@ The option `expand` can be used to control which lists are expanded initially. T
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude-flat:: _static/example.json
                 :jsonpointer: /a/0/b
                 :recursive:
@@ -117,7 +117,7 @@ The option `expand` can be used to control which lists are expanded initially. T
 
         .. literal-and-parsed-markdown::
 
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude-flat:: _static/example.json
                 :jsonpointer: /h
             ```
@@ -126,7 +126,7 @@ The option `expand` can be used to control which lists are expanded initially. T
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsoninclude-flat:: _static/example.json
                 :jsonpointer: /a/0/b
                 :ignore_path: /a/0/b/

docs/jsonschema.md

@@ -1,6 +1,6 @@
 # JSON Schema Directives
 
-`````eval_rst
+`````{eval-rst}
 
 .. rst:directive:: jsonschema
         
@@ -14,7 +14,7 @@
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsonschema:: _static/example_schema.json
             ```
 
@@ -26,13 +26,13 @@
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsonschema-titles:: _static/example_schema.json
             ```
 
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsonschema-titles:: _static/example_schema.json
                 :child: subthings
             ```
@@ -45,7 +45,7 @@
   
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsonschema-title-fieldname-map:: _static/example_schema.json
             ```
 
@@ -58,7 +58,7 @@
   
         .. literal-and-parsed-markdown::
             
-            ```eval_rst
+            ```{eval-rst}
             .. jsonschema-array:: _static/example_schema_array.json
             ```
 

docs/misc.md

@@ -1,6 +1,6 @@
 # Misc Directives
 
-`````eval_rst
+`````{eval-rst}
 
 .. rst:directive:: csv-table-no-translate
 
@@ -21,7 +21,7 @@
 
         .. literal-and-parsed-markdown::
 
-            ```eval_rst
+            ```{eval-rst}
             .. markdown::
 
                 Some markdown [a URL](http://example.org), `single backtick literals`. 
@@ -32,7 +32,7 @@
 
         .. literal-and-parsed-markdown::
 
-            ```eval_rst
+            ```{eval-rst}
             .. admonition:: Worked example
                 :class: hint
 
@@ -53,7 +53,7 @@
 
         .. literal-and-parsed-markdown::
 
-            ```eval_rst
+            ```{eval-rst}
             .. directory_list::
                 :path: exampledir
                 :url: https://github.com/OpenDataServices/sphinxcontrib-opendataservices/blob/master/docs/exampledir/
@@ -63,7 +63,7 @@
    
    Create a note admonition that only will appear in languages that have "translated" it. This will not appear in the base language (normally English). If a translator wants to mark they have seen the message but do not want to add a note then they can leave a single hyphen '-'. The contents of the translation will be treated as markdown. The text within the directive should contain information useful for the translator and instruct what to do when they encouter this. For example::
 
-    ```eval_rst
+    ```{eval-rst}
     .. localization-note:: 
 
       DO NOT TRANSLATE THIS MESSAGE DIRECTLY

setup.py

@@ -2,7 +2,7 @@
 
 setup(
     name='sphinxcontrib-opendataservices',
-    version='0.1.0',
+    version='0.1.1',
     author='Open Data Services',
     author_email='[email protected]',
     packages=['sphinxcontrib'],
@@ -21,7 +21,6 @@
             'flake8',
             'isort',
             'lxml',
-            'myst-parser',
             'pytest',
             'pytest-cov',
         ],

sphinxcontrib/opendataservices.py

@@ -12,7 +12,7 @@
 from docutils.parsers.rst.directives.tables import CSVTable
 from docutils.parsers.rst.roles import set_classes
 from docutils.transforms import Transform
-from docutils.utils import SystemMessagePropagation
+from docutils.utils import SystemMessagePropagation, new_document
 from jsonpointer import resolve_pointer
 from myst_parser.main import to_docutils
 from recommonmark.transform import AutoStructify
@@ -232,16 +232,18 @@ def run(self):
         return [bl]
 
 
-def parse_markdown(text):
-    return to_docutils(text).children[:]
+def parse_markdown(text, document=None):
+    if document:
+        document = new_document(None, document.settings)
+    return to_docutils(text, document=document).children[:]
 
 
 class MarkdownDirective(Directive):
     has_content = True
 
     def run(self):
         text = '\n'.join(self.content)
-        return parse_markdown(text)
+        return parse_markdown(text, document=self.state.document)
 
 
 class LiteralAndParsedMarkdownDirective(Directive):
@@ -253,7 +255,7 @@ def run(self):
             nodes.paragraph('', '', nodes.Text('Source:')),
             nodes.literal_block(text, text),
             nodes.paragraph('', '', nodes.Text('Output:')),
-        ] + parse_markdown(text)
+        ] + parse_markdown(text, document=self.state.document)
 
 
 def type_format_simple(prop):