Merge pull request #1213 from open-contracting/myst-parser-switch

Updating requirements for myst-parser

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
       run: |
         if [ $GITHUB_REPOSITORY = 'open-contracting/standard_profile_template' ]; then python schema/build-profile.py; make extract; fi
         make
-        python util/add_translation_notes.py
+      python util/add_translation_notes.py
     - run: pytest
     - uses: shimataro/ssh-key-action@v2
       with:

common-requirements.in

@@ -1,11 +1,11 @@
-Sphinx<3
+-e git+https://github.com/sphinx-doc/sphinx.git@3207da1fa81a5d3171d3bbb15768e1c6f6b39b58#egg=sphinx
 
 # Sphinx
 ocds-babel>=0.2.1
 # See https://ocds-babel.readthedocs.io/en/latest/api/translate.html#install-requirements-for-markdown-translation
--e git+https://github.com/readthedocs/commonmark.py.git@dafae75015cc342f3fddb499674bab97ac4a6a96#egg=commonmark
--e git+https://github.com/jpmckinney/recommonmark.git@hotfix#egg=recommonmark
 -e git+https://github.com/open-contracting/standard_theme.git@open_contracting#egg=standard_theme
+myst-parser~=0.13.3
+mdit-py-plugins~=0.2.5
 
 # Make
 sphinx-intl<1
@@ -18,5 +18,6 @@ ocdsindex>=0.0.4
 ocdsextensionregistry>=0.0.23
 
 # Tests
+pip-tools
 pytest
 selenium

common-requirements.txt

@@ -4,18 +4,19 @@
 #
 #    pip-compile common-requirements.in
 #
--e git+https://github.com/readthedocs/commonmark.py.git@dafae75015cc342f3fddb499674bab97ac4a6a96#egg=commonmark
+-e git+https://github.com/sphinx-doc/sphinx.git@3207da1fa81a5d3171d3bbb15768e1c6f6b39b58#egg=sphinx
     # via
     #   -r common-requirements.in
-    #   recommonmark
--e git+https://github.com/jpmckinney/recommonmark.git@hotfix#egg=recommonmark
-    # via -r common-requirements.in
+    #   myst-parser
+    #   sphinx-intl
 -e git+https://github.com/open-contracting/standard_theme.git@open_contracting#egg=standard_theme
     # via -r common-requirements.in
 alabaster==0.7.12
     # via sphinx
 attrs==19.3.0
-    # via pytest
+    # via
+    #   markdown-it-py
+    #   pytest
 babel==2.8.0
     # via
     #   sphinx
@@ -29,10 +30,11 @@ chardet==3.0.4
 click==7.0
     # via
     #   ocdsindex
+    #   pip-tools
     #   sphinx-intl
 docutils==0.16
     # via
-    #   recommonmark
+    #   myst-parser
     #   sphinx
 elasticsearch==7.10.1
     # via ocdsindex
@@ -45,17 +47,30 @@ importlib-metadata==1.4.0
     #   pluggy
     #   pytest
 jinja2==2.10.3
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 json-merge-patch==0.2
     # via ocdsextensionregistry
 jsonref==0.2
     # via ocdsextensionregistry
 lxml==4.6.2
     # via ocdsindex
+markdown-it-py==0.6.1
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==1.1.1
     # via jinja2
+mdit-py-plugins==0.2.5
+    # via
+    #   -r common-requirements.in
+    #   markdown-it-py
+    #   myst-parser
 more-itertools==8.1.0
     # via pytest
+myst-parser==0.13.3
+    # via -r common-requirements.in
 ocds-babel==0.2.1
     # via -r common-requirements.in
 ocdsextensionregistry==0.0.23
@@ -66,6 +81,8 @@ packaging==20.0
     # via
     #   pytest
     #   sphinx
+pip-tools==5.5.0
+    # via -r common-requirements.in
 pluggy==0.13.1
     # via pytest
 py==1.8.1
@@ -80,6 +97,8 @@ python-slugify==1.2.6
     # via transifex-client
 pytz==2019.3
     # via babel
+pyyaml==5.4.1
+    # via myst-parser
 requests-cache==0.5.2
     # via ocdsextensionregistry
 requests==2.22.0
@@ -99,11 +118,6 @@ snowballstemmer==2.0.0
     # via sphinx
 sphinx-intl==0.9.12
     # via -r common-requirements.in
-sphinx==2.4.4
-    # via
-    #   -r common-requirements.in
-    #   recommonmark
-    #   sphinx-intl
 sphinxcontrib-applehelp==1.0.1
     # via sphinx
 sphinxcontrib-devhelp==1.0.1
@@ -132,4 +146,5 @@ zipp==1.0.0
     # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
+# pip
 # setuptools

docs/404.md

@@ -1,6 +1,6 @@
-```eval_rst
-:orphan:
-```
+---
+orphan: true
+---
 
 # 404 Not found
 

docs/_static/basic.css

@@ -2,6 +2,11 @@ div.spaced li {
   margin-bottom: 1em;
 }
 
+.directive--field-description,
+.directive--code-description {
+  font-style: italic;
+}
+
 /* Extensions */
 .hide {
   display: none;

docs/conf.py

@@ -19,7 +19,6 @@
 
 import standard_theme
 from ocds_babel.translate import translate
-from recommonmark.transform import AutoStructify
 
 # -- Project information -----------------------------------------------------
 
@@ -37,10 +36,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'recommonmark',
     'sphinxcontrib.jsonschema',
     'sphinxcontrib.opencontracting',
     'sphinxcontrib.opendataservices',
+    'myst_parser',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -103,16 +102,12 @@
     'process_title': default_extension_version,
 }
 
+# Disable dollarmath, which uses MathJax for a string like: "If Alice has $100 and Bob has $1..."
+# https://myst-parser.readthedocs.io/en/latest/using/intro.html#sphinx-configuration-options
+myst_enable_extensions = []
 
-def setup(app):
-    app.add_config_value('extension_versions', extension_versions, True)
-    app.add_config_value('recommonmark_config', {
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True
-    }, True)
-
-    app.add_transform(AutoStructify)
 
+def setup(app):
     # The root of the repository.
     basedir = Path(os.path.realpath(__file__)).parents[1]
     # The `LOCALE_DIR` from `config.mk`.

docs/getting_started/building_blocks.md

@@ -1,4 +1,4 @@
-## Building Blocks
+# Building Blocks
 
 In mapping your data to OCDS, or using OCDS data, you will encounter a number of common data structures.
 
@@ -12,7 +12,7 @@ In mapping your data to OCDS, or using OCDS data, you will encounter a number of
     </tr>
 </table>
 
-### Sections and structure
+## Sections and structure
 
 An OCDS document is made up of a number of sections. These are:
 
@@ -26,7 +26,7 @@ An OCDS document is made up of a number of sections. These are:
 
 These are represented in a JSON document as follows:
 
-```eval_rst
+```{eval-rst}
 .. code-block:: json
    :emphasize-lines: 8-13
        
@@ -48,7 +48,7 @@ These are represented in a JSON document as follows:
         }
 ```
 
-### Building blocks: fields
+## Building blocks: fields
 
 The OCDS schema sets out the fields that ought to be included in each section (where applicable), making use of simple re-usable building blocks (field structures) to represent data. 
 
@@ -61,57 +61,57 @@ For example, common building blocks are provided for:
 * **Documents** 
 * **Milestones**
 
-#### Examples
+### Examples
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/record.json
    :jsonpointer: /records/0/compiledRelease/parties/0
    :expand: identifier, address, contactPoint
    :title: party
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/record.json
    :jsonpointer: /records/0/compiledRelease/awards/0/value
    :expand: 
    :title: amounts
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/record.json
    :jsonpointer: /records/0/compiledRelease/awards/0/items
    :expand: classification, unit, additionalClassifications, value
    :title: items
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/record.json
    :jsonpointer: /records/0/compiledRelease/awards/0/contractPeriod
    :expand: 
    :title: period
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/record.json
    :jsonpointer: /records/0/compiledRelease/awards/0/documents
    :expand: 
    :title: documents
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/record.json
    :jsonpointer: /records/0/compiledRelease/tender/milestones/0
    :expand: 
    :title: milestones
 
 ```
 
-#### Using building blocks
+### Using building blocks
 
 These building blocks can be used in various different sections. For example, **items** can occur in tender (to indicate the items that a buyer wishes to buy), in an award object (to indicate the items that an award has been made for) and in a contract object (to indicate the items listed in the contract). 
 
@@ -125,7 +125,7 @@ In addition to these building blocks, the OCDS schema sets out the specific ways
 
 Many of these fields make use of lightweight codelists provided by OCDS. 
 
-#### Extensions
+### Extensions
 
 In some cases, publishers or users need building blocks and fields which are not provided in the core OCDS schema. 
 
@@ -139,7 +139,7 @@ The Open Contracting Data Standard helpdesk maintain a [field-level mapping temp
 
 </div>
 
-### Codelists
+## Codelists
 
 OCDS defines two kinds of codelist:
 
@@ -165,7 +165,7 @@ In the EU, contracts can be initiated through a number of different procedures i
 
 However, to support comparison across continents, the main OCDS procurement method codelist is a closed codelist with four values:
 
-```eval_rst
+```{eval-rst}
 .. codelisttable::
    :header-rows: 1
    :file: ../../build/current_lang/codelists/method.csv

docs/getting_started/contracting_process.md

@@ -1,4 +1,4 @@
-## The Contracting Process
+# The Contracting Process
 
 There are several stages to a contracting process.
 
@@ -90,15 +90,15 @@ You are encouraged to publish OCDS data close to real-time: releasing data as ea
 
 This might involve generating output from a range of different systems. Data published from different systems can be tied together by use of a common Open Contracting ID (`ocid`).
 
-### Defining a contracting process
+## Defining a contracting process
 
 For public procurement OCDS defines a unique contracting process as:
 
 > All the planning, tendering information, awards, contracts and contract implementation information related to a single initiation process.
 
 An initiation process might be a tender, a direct contract award, or a call to award a concession.
 
-### The Open Contracting ID (ocid)
+## The Open Contracting ID (ocid)
 
 Each unique contracting process needs to be assigned an `ocid`. This is an identifier which can be used to join up data between different stages (as often the data might be stored in different systems).
 
@@ -136,6 +136,6 @@ The `ocid` is case sensitive. Case needs to be used consistently whenever an `oc
 
 </div>
 
-### Mapping your systems
+## Mapping your systems
 
 The Open Contracting Data Standard helpdesk provide [a technical assessment template](http://www.open-contracting.org/resources/ocds-technical-assessment-template/) that can be used to identify the different systems involved in managing data on each stage of the contracting process.

docs/getting_started/index.md

@@ -18,14 +18,14 @@ To get started publishing OCDS data:
 
 When you are done you could be producing data that looks something like the contract release below, which is compatible with a growing range of OCDS aware tools (you will encounter a range of different OCDS release types in the following pages).
 
-```eval_rst
+```{eval-rst}
 .. jsoninclude:: ../examples/contract.json
    :jsonpointer: /releases
    :expand: releases, tender, awards, contracts, period, value, items, tag, parties, documents
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden: