docs: use Sphinx extension to generate CLI options

docs/conf.py

@@ -1,14 +1,11 @@
 import os
+import sys
 import re
 import json
 import subprocess
 import urllib.request
-from docutils import nodes
 
-from sphinx.util import console
 from sphinx.errors import SphinxError
-from recommonmark.parser import CommonMarkParser
-from recommonmark.transform import AutoStructify
 
 
 ###########################################################################
@@ -20,11 +17,16 @@
 
 # -- Environment ----------------------------------------------------------
 
+# Explicitly put the extensions directory to Python path
+sys.path.append(os.path.abspath('extensions'))
+
+# Detect whether the build happens on ReadTheDocs
 IS_READTHEDOCS = os.environ.get('READTHEDOCS') == 'True'
 
 # Specify paths
 docs_dir = os.path.dirname(__file__)
 project_dir = os.path.join(docs_dir, '..')
+extensions_dir = os.path.join(docs_dir, 'extensions')
 node_modules_bin_dir = os.path.join(project_dir, 'node_modules', '.bin')
 
 # Install all npm dependencies if on ReadTheDocs. This requires the latest
@@ -44,6 +46,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'cli_options',
     'pygments_markdown_lexer',
 ]
 
@@ -164,12 +167,6 @@ def get_release():
 ]
 
 
-# -- Custom Extensions ----------------------------------------------------
-
-def setup(app):
-    pass
-
-
 # -- Hacks ----------------------------------------------------------------
 
 import sphinx.application

docs/extensions/cli_options.py

@@ -0,0 +1,55 @@
+import os
+import json
+from textwrap import dedent
+from docutils import nodes
+from docutils.statemachine import ViewList
+
+from jinja2 import Template
+from sphinx.util.compat import Directive
+from sphinx.util.nodes import nested_parse_with_titles
+
+
+class CLIOptionsDirective(Directive):
+    required_arguments = 1
+
+    def run(self):
+        # Load options from given JSON file
+        options_path = os.path.join(
+            os.path.dirname(self.state.document['source']),
+            self.arguments[0],
+        )
+        with open(options_path) as f:
+            options = json.load(f)
+
+        # Generate reStructuredText markup
+        rst = ''
+        for name, attrs in sorted(options.items()):
+            data = {
+                'name': name,
+                'alias': attrs.get('alias'),
+                'default': json.dumps(attrs['default']) if 'default' in attrs else None,
+                'description': attrs['description'],
+            }
+            template = Template(dedent('''
+                .. _{{ name }}{% if alias %}-{{ alias }}{% endif %}:
+
+                .. option:: --{{ name }}{% if alias %}, -{{ alias }}{% endif %}
+
+                    {{ description }}
+                    {% if default %}**Default value:** ``{{ default }}``{% endif %}
+
+            '''))
+            rst += template.render(**data)
+
+        # Generate docutils nodes
+        result = ViewList()
+        for line in rst.splitlines():
+            result.append(line, f'<cli-options-directive>')
+        node = nodes.section(document=self.state.document)
+        nested_parse_with_titles(self.state, result, node)
+        return node.children
+
+
+def setup(app):
+    app.add_directive('cli-options', CLIOptionsDirective)
+    return {'version': '1.0', 'parallel_read_safe': True}

docs/requirements.txt

@@ -4,3 +4,4 @@ sphinx-rtd-theme==0.2.4
 pygments-markdown-lexer==0.1.0.dev39
 pygments-apiblueprint==0.1.0
 doc8==0.8.0
+jinja2==2.10

docs/usage-cli.rst

@@ -3,69 +3,63 @@
 Command-line Interface
 ======================
 
-.. _api-description-document-string:
-.. _path-p:
-.. _hooks-worker-timeout:
-.. _hooks-worker-connect-timeout:
-.. _hooks-worker-connect-retry:
-.. _hooks-worker-after-connect-wait:
-.. _hooks-worker-term-timeout:
-.. _hooks-worker-term-retry:
-.. _hooks-worker-handler-host:
-.. _hooks-worker-handler-port:
-
-Foo bar
--------
+Usage
+-----
 
-..
-   # Command-line Interface
+::
 
-   ## Usage
-
-   ```
    $ dredd '<API Description Document>' '<API Location>' [OPTIONS]
-   ```
 
-   Example:
+Example:
+
+::
 
-   ```
    $ dredd ./apiary.md http://127.0.0.1:3000
-   ```
 
-   ## Arguments
+Arguments
+---------
+
+.. _api-description-document-string:
+
+API Description Document (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   ### API Description Document (string)
+URL or path to the API description document (API Blueprint, Swagger).
 
-   URL or path to the API description document (API Blueprint, Swagger).<br>
-   **Sample values:** `./api-blueprint.apib`, `./swagger.yml`, `./swagger.json`, `http://example.com/api-blueprint.apib`
+**Sample values:** ``./api-blueprint.apib``, ``./swagger.yml``, ``./swagger.json``, ``http://example.com/api-blueprint.apib``
 
-   ### API Location (string)
+.. _api-location-string:
 
-   URL, the root address of your API.<br>
-   **Sample values:** `http://127.0.0.1:3000`, `http://api.example.com`
+API Location (string)
+~~~~~~~~~~~~~~~~~~~~~
 
-   ## Configuration File
+URL, the root address of your API.
 
-   If you use Dredd repeatedly within a single project, the preferred way to run it is to first persist your configuration in a `dredd.yml` file. With the file in place you can then run Dredd every time simply just by:
+**Sample values:** ``http://127.0.0.1:3000``, ``http://api.example.com``
+
+Configuration File
+------------------
+
+If you use Dredd repeatedly within a single project, the preferred way to run it is to first persist your configuration in a ``dredd.yml`` file. With the file in place you can then run Dredd every time simply just by:
+
+::
 
-   ```
    $ dredd
-   ```
 
-   Dredd offers interactive wizard to setup your `dredd.yml` file:
+Dredd offers interactive wizard to setup your ``dredd.yml`` file:
+
+::
 
-   ```
    $ dredd init
-   ```
 
-   See below how sample configuration file could look like. The structure is
-   the same as of the [Dredd Class configuration object](usage-js.md#configuration-object-for-dredd-class).
+See below how sample configuration file could look like. The structure is the same as of the :ref:`Dredd Class configuration object <configuration-object-for-dredd-class>`.
+
+.. code-block:: yaml
 
-   ```yaml
    reporter: apiary
    custom:
-   - "apiaryApiKey:yourSecretApiaryAPiKey"
-   - "apiaryApiName:apiName"
+     - "apiaryApiKey:yourSecretApiaryAPiKey"
+     - "apiaryApiName:apiName"
    dry-run: null
    hookfiles: "dreddhooks.js"
    sandbox: false
@@ -88,22 +82,15 @@ Foo bar
    path: []
    blueprint: api-description.apib
    endpoint: "http://127.0.0.1:3000"
-   ```
-
-   > **Note:** Do not get confused by Dredd using a keyword `blueprint` also for paths to Swagger documents. This is for historical reasons and will be changed in the future.
-
-   ## CLI Options Reference
 
-   Remember you can always list all available arguments by `dredd --help`.
+.. note::
+   Do not get confused by Dredd using a keyword ``blueprint`` also for paths to Swagger documents. This is for historical reasons and will be changed in the future.
 
-   <% for option in @options: %>
-   <a name="-<%= option.name %><% if option.alias: %>-<%= option.alias %><% end %>"></a><!-- legacy MkDocs anchor -->
+CLI Options Reference
+---------------------
 
-   ### \-\-<%= option.name %><% if option.alias: %>, -<%= option.alias %><% end %>
+Remember you can always list all available arguments by ``dredd --help``.
 
-   <%= option.description %><br>
-   <% if option.default: %>
-   **Default value:** `<%- JSON.stringify(option.default) %>`
-   <% end %>
+.. program:: dredd
 
-   <% end %>
+.. cli-options:: ../src/options.json