diff --git a/README.rst b/README.rst index 506e644..20fd176 100644 --- a/README.rst +++ b/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 `__ 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 `__. |Sample +example `__. |Sample output| JSON output @@ -66,4 +103,4 @@ License Released under the `MIT License `__. -.. |Sample output| image:: http://charonex.com/img/evedocs-example.png +.. |Sample output| image:: https://github.com/hermannsblum/eve-docs/blob/extended_documentation/screenshot.png diff --git a/eve_docs/config.py b/eve_docs/config.py index 16f83c2..a89e11e 100644 --- a/eve_docs/config.py +++ b/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: diff --git a/eve_docs/templates/evedocstyle.html b/eve_docs/templates/evedocstyle.html index 653ccb7..ffff7c8 100644 --- a/eve_docs/templates/evedocstyle.html +++ b/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; +} diff --git a/eve_docs/templates/macros.html b/eve_docs/templates/macros.html index 1c2b64b..2f02573 100644 --- a/eve_docs/templates/macros.html +++ b/eve_docs/templates/macros.html @@ -1,4 +1,4 @@ -{% macro accordian(domain, paths) -%} +{% macro accordian(domain, definition) -%}

{%- endmacro %} -{% macro params_table(params) -%} +{% macro params_table(params, description) -%} @@ -54,11 +66,17 @@

{% for param in params %} + {% set name = param.pop('name') %} - +
{{ param.pop('name') }}{{ name }} {{ param.pop('type') }} {{ param.pop('required') }} + {% if description[name] %} + + {{ description[name]}} +
+ {%- endif %} {% for key, value in param.items() %} {{ key }}: {{ value }}
{% endfor %} diff --git a/screenshot.png b/screenshot.png new file mode 100644 index 0000000..49ce4b4 Binary files /dev/null and b/screenshot.png differ diff --git a/screenshot_expanded.png b/screenshot_expanded.png new file mode 100644 index 0000000..94afd5f Binary files /dev/null and b/screenshot_expanded.png differ diff --git a/settings.py b/settings.py index f7b70a7..e41d103 100644 --- a/settings.py +++ b/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.' + } } }