Improve parameter documentation

core-api · Dec 1, 2016 · 49c8c4d · 49c8c4d
1 parent a54c4f1
commit 49c8c4d
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 14 deletions.
diff --git a/coredocs/__init__.py b/coredocs/__init__.py
@@ -1 +1 @@
-__version__ = '0.0.2'
+__version__ = '0.0.3'
diff --git a/coredocs/main.py b/coredocs/main.py
@@ -17,6 +17,10 @@
 DEFAULT_LANGS = ['shell', 'python']
 
 
+def get_fields(location, link):
+    return [field for field in link.fields if field.location == location]
+
+
 def render(doc, highlight=None, langs=None, static=None):
     if static is None:
         static = lambda path: path
@@ -37,6 +41,7 @@ def render(doc, highlight=None, langs=None, static=None):
         document=doc,
         get_sections=get_sections,
         get_links=get_links,
+        get_fields=get_fields,
         code_style=get_highlight_css(highlight),
         schema_url=doc.url,
         langs=langs,

diff --git a/coredocs/templates/coreapi/link.html b/coredocs/templates/coreapi/link.html
@@ -11,16 +11,72 @@ <h3>HTTP Request</h3>
     <code>{{ link.action|upper }} {{ link.url }}</code>
 </p>
 
-{% if link.fields %}
-<h3>Parameters</h3>
-<table>
-    <thead>
-        <tr><th>Parameter</th><th>Location</th><th>Description</th></tr>
-    </thead>
-    <tbody>
-        {% for field in link.fields %}
-        <tr><td>{{ field.name }}</td><td>{{ field.location }}</td><td>{% if field.description %}{{ field.description }}{% endif %}</td></tr>
-        {% endfor %}
-    </tbody>
-</table>
+{% if get_fields('path', link ) %}
+    <h3>Path Parameters</h3>
+    <p>The following parameters should be included in the URL path.</p>
+    <table class="parameters">
+        <thead>
+            <tr><th>Parameter</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+            {% for field in get_fields('path', link ) %}
+            <tr><td><code>{{ field.name }}</code>{% if field.required %} <strong>required</strong>{% endif %}</td><td>{% if field.description %}{{ field.description }}{% endif %}</td></tr>
+            {% endfor %}
+        </tbody>
+    </table>
+{% endif %}
+{% if get_fields('query', link ) %}
+    <h3>Query Parameters</h3>
+    <p>The following parameters should be included as part of a URL query string.</p>
+    <table class="parameters">
+        <thead>
+            <tr><th>Parameter</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+            {% for field in get_fields('query', link ) %}
+            <tr><td><code>{{ field.name }}</code>{% if field.required %} <strong>required</strong>{% endif %}</td><td>{% if field.description %}{{ field.description }}{% endif %}</td></tr>
+            {% endfor %}
+        </tbody>
+    </table>
+{% endif %}
+{% if get_fields('header', link ) %}
+    <h3>Header Parameters</h3>
+    <p>The following parameters should be included as HTTP headers.</p>
+    <table class="parameters">
+        <thead>
+            <tr><th>Parameter</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+            {% for field in get_fields('header', link ) %}
+            <tr><td><code>{{ field.name }}</code>{% if field.required %} <strong>required</strong>{% endif %}</td><td>{% if field.description %}{{ field.description }}{% endif %}</td></tr>
+            {% endfor %}
+        </tbody>
+    </table>
+{% endif %}
+{% if get_fields('body', link ) %}
+    <h3>Request Body</h3>
+    <p>The request body should be <code>"{{ link.encoding }}"</code> encoded, and should contain a single item.</p>
+    <table class="parameters">
+        <thead>
+            <tr><th>Parameter</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+            {% for field in get_fields('body', link ) %}
+            <tr><td><code>{{ field.name }}</code>{% if field.required %} <strong>required</strong>{% endif %}</td><td>{% if field.description %}{{ field.description }}{% endif %}</td></tr>
+            {% endfor %}
+        </tbody>
+    </table>
+{% elif get_fields('form', link ) %}
+    <h3>Request Body</h3>
+    <p>The request body should be a <code>"{{ link.encoding }}"</code> encoded object, containing the following&nbsp;items.</p>
+    <table class="parameters">
+        <thead>
+            <tr><th>Parameter</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+            {% for field in get_fields('form', link ) %}
+            <tr><td><code>{{ field.name }}</code>{% if field.required %} <strong>required</strong>{% endif %}</td><td>{% if field.description %}{{ field.description }}{% endif %}</td></tr>
+            {% endfor %}
+        </tbody>
+    </table>
 {% endif %}
diff --git a/coredocs/templates/languages/shell.html b/coredocs/templates/languages/shell.html
@@ -2,4 +2,4 @@
 $ coreapi get {{ schema_url }}{% if schema_format %} --format {{ schema_format }}{% endif %}
 
 # Interact with the API endpoint
-$ coreapi action {{ section_key }} {{ link_key }}{% for field in link.fields %} {{ field.name }}=...{% endfor %}{% endhighlight %}</code></pre>
+$ coreapi action {{ section_key }} {{ link_key }}{% for field in link.fields %} -p {{ field.name }}=...{% endfor %}{% endhighlight %}</code></pre>
diff --git a/coredocs/templates/slate/index.html b/coredocs/templates/slate/index.html
@@ -8,6 +8,10 @@
     <link href="{{ static('slate/stylesheets/screen.css') }}" rel="stylesheet" media="screen" />
     <link href="{{ static('slate/stylesheets/print.css') }}" rel="stylesheet" media="print" />
     <script src="{{ static('slate/javascripts/all.js') }}"></script>
+    <style>
+        table.parameters strong {color: orange}
+        table.parameters code {background-color: transparent}
+    </style>
     <style>{{ code_style }}</style>
   </head>