Switch from m2r to sphinx-mdinclude

m2r is unmaintained [0]. It relies on mistune, but is not compatible with
mistune versions >= 2.0 [1]. This makes it impossible to update mistune,
even though there is a CVE in the old versions of the package [2].

Switch to sphinx-mdinclude instead.

There is also m2r2, but it is not a suitable alternative because they
simply force the use of an older mistune version [3].

[0] sphinx-contrib#123
[1] miyakogi/m2r#66
[2] GHSA-fw3v-x4f2-v673
[3] CrossNox/m2r2#43

Fixes: sphinx-contrib#123

setup.py

@@ -30,7 +30,7 @@
         "sphinxcontrib-httpdomain >= 1.5.0",
         "PyYAML >= 3.12",
         "jsonschema >= 2.5.1",
-        "m2r >= 0.2",
+        "sphinx-mdinclude >= 0.5.2",
         "picobox >= 2.2",
         "deepmerge >= 0.1",
     ],

sphinxcontrib/openapi/renderers/_httpdomain.py

@@ -9,7 +9,7 @@
 
 import deepmerge
 import docutils.parsers.rst.directives as directives
-import m2r
+import sphinx_mdinclude
 import requests
 import sphinx.util.logging as logging
 
@@ -184,7 +184,10 @@ def _get_schema_type(schema):
 class HttpdomainRenderer(abc.RestructuredTextRenderer):
     """Render OpenAPI v3 using `sphinxcontrib-httpdomain` extension."""
 
-    _markup_converters = {"commonmark": m2r.convert, "restructuredtext": lambda x: x}
+    _markup_converters = {
+        "commonmark": sphinx_mdinclude.convert,
+        "restructuredtext": lambda x: x,
+    }
     _response_examples_for = {"200", "201", "202", "2XX"}
     _request_parameters_order = ["header", "path", "query", "cookie"]
 

sphinxcontrib/openapi/utils.py

@@ -17,7 +17,7 @@
 import jsonschema
 import yaml
 try:
-    from m2r import convert as convert_markdown
+    from sphinx_mdinclude import convert as convert_markdown
 except ImportError:
     convert_markdown = None
 

tests/renderers/httpdomain/rendered/v2.0/uber.json.rst

@@ -36,11 +36,11 @@
 
    **Price Estimates**
 
-   .. role:: raw-html-m2r(raw)
+   .. role:: raw-html-md(raw)
       :format: html
 
 
-   The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-m2r:`<br>`\ :raw-html-m2r:`<br>`\ The response also includes low and high estimates, and the `ISO 4217 <http://en.wikipedia.org/wiki/ISO_4217>`_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.
+   The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-md:`<br>`\ :raw-html-md:`<br>`\ The response also includes low and high estimates, and the `ISO 4217 <http://en.wikipedia.org/wiki/ISO_4217>`_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.
 
    :queryparam start_latitude:
       Latitude component of start location.
@@ -154,11 +154,11 @@
 
    **User Activity**
 
-   .. role:: raw-html-m2r(raw)
+   .. role:: raw-html-md(raw)
       :format: html
 
 
-   The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-m2r:`<br>`\ :raw-html-m2r:`<br>`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
+   The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-md:`<br>`\ :raw-html-md:`<br>`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
 
    :queryparam offset:
       Offset the list of returned results by this amount. Default is zero.

tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst

@@ -36,11 +36,11 @@
 
    **Price Estimates**
 
-   .. role:: raw-html-m2r(raw)
+   .. role:: raw-html-md(raw)
       :format: html
 
 
-   The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-m2r:`<br>`\ :raw-html-m2r:`<br>`\ The response also includes low and high estimates, and the `ISO 4217 <http://en.wikipedia.org/wiki/ISO_4217>`_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.
+   The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-md:`<br>`\ :raw-html-md:`<br>`\ The response also includes low and high estimates, and the `ISO 4217 <http://en.wikipedia.org/wiki/ISO_4217>`_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.
 
    :queryparam start_latitude:
       Latitude component of start location.
@@ -154,11 +154,11 @@
 
    **User Activity**
 
-   .. role:: raw-html-m2r(raw)
+   .. role:: raw-html-md(raw)
       :format: html
 
 
-   The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-m2r:`<br>`\ :raw-html-m2r:`<br>`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
+   The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-md:`<br>`\ :raw-html-md:`<br>`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
 
    :queryparam offset:
       Offset the list of returned results by this amount. Default is zero.