Merge pull request #127 from qmonnet/pr/mdinclude

Fixes #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

@@ -16,10 +16,7 @@
 from contextlib import closing
 import jsonschema
 import yaml
-try:
-    from m2r import convert as convert_markdown
-except ImportError:
-    convert_markdown = None
+import sphinx_mdinclude
 
 from urllib.parse import urlsplit
 from urllib.request import urlopen
@@ -113,12 +110,7 @@ def get_text_converter(options):
     """Decide on a text converter for prose."""
     if 'format' in options:
         if options['format'] == 'markdown':
-            if convert_markdown is None:
-                raise ValueError(
-                    "Markdown conversion isn't available, "
-                    "install the [markdown] extra."
-                )
-            return convert_markdown
+            return sphinx_mdinclude.convert
 
     # No conversion needed.
     return lambda s: s

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.

tests/testspecs/v2.0/uber.json

@@ -61,7 +61,7 @@
     "/estimates/price": {
       "get": {
         "summary": "Price Estimates",
-        "description": "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.<br><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.",
+        "description": "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.<br /><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.",
         "parameters": [
           {
             "name": "start_latitude",
@@ -201,7 +201,7 @@
     "/history": {
       "get": {
         "summary": "User Activity",
-        "description": "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.<br><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.",
+        "description": "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.<br /><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.",
         "parameters": [
           {
             "name": "offset",

tests/testspecs/v2.0/uber.yaml

@@ -55,7 +55,7 @@ paths:
   /estimates/price:
     get:
       summary: Price Estimates
-      description: 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.<br><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.
+      description: 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.<br /><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.
       parameters:
         - name: start_latitude
           in: query
@@ -151,7 +151,7 @@ paths:
   /history:
     get:
       summary: User Activity
-      description: 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.<br><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.
+      description: 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.<br /><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.
       parameters:
         - name: offset
           in: query