Extended Documentation

README.rst

@@ -25,6 +25,43 @@ defined in your launch script. ``example.py`` shows how to do this using
 the launch script from Nicola Iarocci's
 `eve-demo <https://github.com/nicolaiarocci/eve-demo>`__ repo.
 
+
+Additional Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may want to add descriptions for resources to eve-docs.
+This is possible by adding an additional key 'description' to the resource 
+definition at the same level as the 'schema'.  
+Inside the description, you can add 3 different types of additional 
+documentation: 
+
+- 'general': A general description of the resource.
+
+- 'methods': For each of the methods eve-docs lists, you can add a 
+method-related description.
+
+- 'fields': You can add a description to each field of the schema.
+
+An example of this additional description can be found in example.py for 
+the 'people' resource:
+
+::  
+
+    'description': {
+            'general': 'Represents people who work at the company.',
+            'methods': {
+                'DELETE': 'DELETE may need special authorization.'
+            },
+            'fields': {
+                'role': 'The role defines the place of this person within the '
+                        'company',
+                'location': 'A dict for the address of this person.',
+                'born': 'Is datetime object, but only the date information is '
+                        'relevant.'
+            }
+        }
+
+
 HTML output
 ~~~~~~~~~~~
 
@@ -33,7 +70,7 @@ The HTML documentation is produced using the
 Expand each domain to show available endpoint methods, and further
 expand each method to show parameter details. A screenshot with one
 method expanded follows, and you can also view a `fully expanded
-example <http://charonex.com/img/evedocs-example2.png>`__. |Sample
+example <https://github.com/hermannsblum/eve-docs/blob/extended_documentation/screenshot_expanded.png>`__. |Sample
 output|
 
 JSON output
@@ -66,4 +103,4 @@ License
 Released under the `MIT
 License <http://www.opensource.org/licenses/MIT>`__.
 
-.. |Sample output| image:: http://charonex.com/img/evedocs-example.png
+.. |Sample output| image:: https://github.com/hermannsblum/eve-docs/blob/extended_documentation/screenshot.png

eve_docs/config.py

@@ -3,6 +3,7 @@
 from .labels import LABELS
 import re
 
+
 def get_cfg():
     cfg = {}
     base = home_link()['href']
@@ -20,7 +21,7 @@ def get_cfg():
             # hide the shadow collection for document versioning
             if 'VERSIONS' not in capp.config or not \
                     domain.endswith(capp.config['VERSIONS']):
-                cfg['domains'][domain] = paths(domain, resource)
+                cfg['domains'][domain] = endpoint_definition(domain, resource)
     return cfg
 
 
@@ -34,6 +35,19 @@ def identifier(resource):
     return ret
 
 
+def endpoint_definition(domain, resource):
+    """
+    gets the documentation of a specified endpoint
+    :param domain: the endpoint
+    :param resource: the resource-subdict of config['DOMAIN']
+    :returns: the documentation as a dict (paths, methods, fields)
+    """
+    ret = {}
+    ret['description'] = resource.get('description', {})
+    ret['paths'] = paths(domain, resource)
+    return ret
+
+
 def schema(resource, field=None):
     ret = []
     if field is not None:

eve_docs/templates/evedocstyle.html

@@ -4,6 +4,11 @@
   font-size: 20px;
 }
 
+.panel_description {
+  margin-bottom: 7px;
+  font-weight: bold;
+}
+
 .method {
   border-style: solid;
   border-width: 1px;
@@ -29,6 +34,12 @@
   margin: 0px;
 }
 
+.method_description {
+  padding: 3px;
+  margin: 7px;
+  font-style: italic;
+}
+
 .method_path {
   float: left;
   padding-bottom: 13px;
@@ -81,4 +92,8 @@
 .method_verb.DELETE {
   background-color: rgba(178, 34, 34, 1);
 }
+
+.param-description {
+  font-style: italic;
+}
 </style>

eve_docs/templates/macros.html

@@ -1,4 +1,4 @@
-{% macro accordian(domain, paths) -%}
+{% macro accordian(domain, definition) -%}
   <div class="panel panel-default">
     <div class="panel-heading">
       <h4 class="panel-title"><a class="accordion-toggle" data-toggle="collapse" 
@@ -8,17 +8,22 @@ <h4 class="panel-title"><a class="accordion-toggle" data-toggle="collapse"
     </div>
     <div id="collapse-{{ domain }}" class="panel-collapse collapse">
       <div class="panel-body">
-        {% for path, method in paths|dictsort %}
+        {% if 'description' in definition and 'general' in definition['description'] %}
+        <div class="panel_description">
+          {{ definition['description']['general'] }}
+        </div>
+        {%- endif %}
+        {% for path, method in definition['paths']|dictsort %}
           {% for method, attrs in method.items() %}
-            {{ method_details(path, method, attrs) }}
+            {{ method_details(definition['description'], path, method, attrs) }}
           {% endfor %}
         {% endfor %}
       </div>
     </div>
   </div>
 {%- endmacro %}
 
-{% macro method_details(path, method, attrs) -%}
+{% macro method_details(description, path, method, attrs) -%}
 {% set pathid = path|replace("{", "")|replace("}", "")|replace("/", "") %}
 <div class="method {{ method }}">
   <a href="#{{ pathid }}-{{ method }}" data-toggle="collapse">
@@ -35,15 +40,22 @@ <h4 class="panel-title"><a class="accordion-toggle" data-toggle="collapse"
       </span>
     </div>
   </a>
-  {% if attrs.params %}
+  {% if attrs.params or description.get('methods')[method]%}
   <div id="{{ pathid }}-{{ method }}" class="collapse">
-    {{ params_table(attrs.params) }}
+    {% if 'methods' in description and method in description['methods'] %}
+      <div class="method_description">
+      {{ description['methods'].get(method) }}
+      </div>
+    {%- endif %}
+    {% if attrs.params %}
+      {{ params_table(attrs.params, description.get('fields')) }}
+    {%- endif %}
   </div>
   {%- endif %}
 </div>
 {%- endmacro %}
 
-{% macro params_table(params) -%}
+{% macro params_table(params, description) -%}
   <table class="table table-striped">
     <thead>
       <tr>
@@ -54,11 +66,17 @@ <h4 class="panel-title"><a class="accordion-toggle" data-toggle="collapse"
       </tr>
     </thead>
   {% for param in params %}
+    {% set name = param.pop('name') %}
     <tr>
-      <td>{{ param.pop('name') }}</td>
+      <td>{{ name }}</td>
       <td>{{ param.pop('type') }}</td>
       <td>{{ param.pop('required') }}</td>
       <td>
+        {% if description[name] %}
+          <span class="param-description">
+            {{ description[name]}}
+          </span><br>
+        {%- endif %}
         {% for key, value in param.items() %}
           {{ key }}: {{ value }}<br/>
         {% endfor %}

settings.py

@@ -106,6 +106,20 @@
         'born': {
             'type': 'datetime',
         },
+    },
+    # The key we defined for special documentaton
+    'description': {
+        'general': 'Represents people who work at the company.',
+        'methods': {
+            'DELETE': 'DELETE may need special authorization.'
+        },
+        'fields': {
+            'role': 'The role defines the place of this person within the '
+                    'company',
+            'location': 'A dict for the address of this person.',
+            'born': 'Is datetime object, but only the date information is '
+                    'relevant.'
+        }
     }
 }