docs: Prototype of Sphinx docs with JavaScript extensions

docs/_extensions/generate-cli-docs.coffee

@@ -0,0 +1,45 @@
+# Generates CLI docs for Dredd.
+#
+# Purpose:
+#   Thanks to this we can be sure the CLI docs are always up-to-date.
+#
+# Usage:
+#
+#       $ cat document-template.md | coffee generate-cli-docs.coffee > document.md
+
+
+fs = require('fs')
+path = require('path')
+ect = require('ect')
+clone = require('clone')
+
+options = require('../../src/options')
+
+
+# Turn options into a sorted array
+data = {options: []}
+
+for own name, attributes of options
+  option = clone(attributes)
+  option.description = option.description.trim()
+  option.name = name
+  data.options.push(option)
+
+data.options.sort((o1, o2) ->
+  switch
+    when o1.name < o2.name then -1
+    when o1.name > o2.name then 1
+    else 0
+)
+
+
+# Process stdin
+source = ''
+process.stdin.on('data', (buffer) ->
+  source += buffer.toString()
+)
+process.stdin.on('end', ->
+  renderer = ect({root: {source}})
+  processedLine = renderer.render('source', data)
+  process.stdout.write(processedLine)
+)

docs/conf.py

@@ -1,12 +1,15 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
 import os
 import subprocess
 
 from recommonmark.parser import CommonMarkParser
+# from recommonmark.transform import AutoStructify
+
 
-# Dredd documentation build configuration file
+###########################################################################
+#                                                                         #
+#    Dredd documentation build configuration file                         #
+#                                                                         #
+###########################################################################
 
 
 # -- General configuration ------------------------------------------------
@@ -15,18 +18,15 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.intersphinx',
     'pygments_markdown_lexer',
 ]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-source_suffix = ['.rst', '.md']
-source_parsers = {
-    '.md': CommonMarkParser,
-}
+source_suffix = '.md'
+source_parsers = {'.md': CommonMarkParser}
 
-# The master toctree document.
+# The master document.
 master_doc = 'index'
 
 # General information about the project.
@@ -48,15 +48,13 @@
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#
-add_function_parentheses = True
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # Suppressed warnings
-suppress_warnings = ['image.nonlocal_uri']
+suppress_warnings = [
+    'image.nonlocal_uri',
+]
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -84,7 +82,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -120,9 +118,65 @@
 # man_show_urls = False
 
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+# -- Custom Extensions ----------------------------------------------------
+
+import subprocess
+from sphinx.errors import SphinxError
+from sphinx.util.console import bold, blue
+
+docs_dir = os.path.dirname(__file__)
+node_modules_bin_dir = os.path.join(docs_dir, '..', 'node_modules', '.bin')
+
+js_extensions = {
+    'hercule': ['node', os.path.join(node_modules_bin_dir, 'hercule'), '--relative=' + docs_dir, '--stdin'],
+}
+js_extensions_dir = os.path.join(docs_dir, '_extensions')
+js_interpreters = {
+    '.js': 'node',
+    '.coffee': os.path.join(node_modules_bin_dir, 'coffee')
+}
+
+
+def init_js_extensions(app):
+    app.info(bold('initializing JavaScript extensions... '), nonl=True)
+    for basename in os.listdir(js_extensions_dir):
+        _, ext = os.path.splitext(basename)
+
+        if ext in js_interpreters.keys():
+            filename = os.path.join(js_extensions_dir, basename)
+            command = [js_interpreters[ext], filename]
+            js_extensions[basename] = command
+
+    if js_extensions:
+        app.connect('source-read', run_js_extensions)
+
+    app.info('{} found'.format(len(js_extensions)))
+    app.verbose('JavaScript extensions: ' + ', '.join(js_extensions.keys()))
+
+
+def run_js_extensions(app, docname, source_list):
+    for name, command in js_extensions.items():
+        app.verbose(bold("runnning JavaScript extension '{}'... ".format(name)) + blue(docname))
+
+        proc = subprocess.Popen(command, stdout=subprocess.PIPE, stdin=subprocess.PIPE)
+        proc.stdin.write(source_list[0].encode('utf-8'))
+        proc.stdin.close()
+        source_list[0] = proc.stdout.read().decode('utf-8')
+        exitStatus = proc.wait()
+
+        if exitStatus:
+            message = "JavaScript extension '{}' finished with non-zero exit status: {}"
+            raise SphinxError(message.format(name, exitStatus))
+
+
+def setup(app):
+    init_js_extensions(app)
 
+    # app.add_config_value('recommonmark_config', {
+    #     'auto_toc_tree_section': 'Contents',
+    #     # 'enable_auto_doc_ref': True,
+    # }, True)
+    # app.add_transform(AutoStructify)
 
 
 # -- Hacks ----------------------------------------------------------------

docs/home.md → docs/index.md

@@ -31,33 +31,30 @@ Dredd supports writing [hooks](https://dredd.readthedocs.io/en/latest/hooks/)
 - [Go](https://dredd.readthedocs.io/en/latest/hooks-go/)
 - [Node.js (JavaScript)](https://dredd.readthedocs.io/en/latest/hooks-nodejs/)
 - [Perl](https://dredd.readthedocs.io/en/latest/hooks-perl/)
-- [PHP](https://dredd.readthedocs.io/en/latest/hook
+- [PHP](https://dredd.readthedocs.io/en/latest/hooks-php/)
 
 - [Travis CI][]
 - [CircleCI][]
 - [Jenkins][]
 - _...and any other \*nix based CI!_
 
-## Documentation Reference
+## Contents
 
-- [About Dredd](index.md)
 - [Installation](installation.md)
 - [Quickstart](quickstart.md)
 - [How It Works](how-it-works.md)
 - [How-To Guides](how-to-guides.md)
-- Usage
-    - [Command-line Interface](usage-cli.md)
-    - [As a JavaScript Library](usage-js.md)
-- Hooks
-    - [About Hooks](hooks.md)
-    - [Go](hooks-go.md)
-    - [JavaScript (Sandboxed)](hooks-js-sandbox.md)
-    - [Node.js](hooks-nodejs.md)
-    - [Perl](hooks-perl.md)
-    - [PHP](hooks-php.md)
-    - [Python](hooks-python.md)
-    - [Ruby](hooks-ruby.md)
-    - [Other Languages](hooks-new-language.md)
+- [Usage: CLI](usage-cli.md)
+- [Usage: JavaScript](usage-js.md)
+- [About Hooks](hooks.md)
+- [Hooks: Go](hooks-go.md)
+- [Hooks: JavaScript (Sandboxed)](hooks-js-sandbox.md)
+- [Hooks: Node.js](hooks-nodejs.md)
+- [Hooks: Perl](hooks-perl.md)
+- [Hooks: PHP](hooks-php.md)
+- [Hooks: Python](hooks-python.md)
+- [Hooks: Ruby](hooks-ruby.md)
+- [Other Languages](hooks-new-language.md)
 - [Data Structures](data-structures.md)
 - [Contributing](contributing.md)