Docs pass 3 (#46)

* enumeration fix.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/source/_templates/enum.md.jinja2

@@ -23,7 +23,7 @@ URI: {{ gen.uri_link(element) }}
 | Value | Meaning | Description |
 | --- | --- | --- |
 {% for pv in element.permissible_values.values() -%}
-| {{pv.text}} | {{pv.meaning}} | {{pv.description|enshorten}} |
+| {{pv.text}} | {{pv.meaning}} | {{pv.description | wordwrap(80, wrapstring='<br/>')}} |
 {% endfor %}
 {% else %}
 _This is a dynamic enum_

docs/source/_templates/index.md.jinja2

@@ -25,7 +25,7 @@ Name: {{ schema.name }}
 {% endfor %}
 {% else -%}
 {% for c in gen.all_class_objects()|sort(attribute=sort_by) -%}
-| {{gen.link(c)}} | {{c.description|enshorten}} |
+| {{gen.link(c)}} | {{c.description | wordwrap(80, wrapstring='<br/>')}} |
 {% endfor %}
 {% endif %}
 
@@ -46,7 +46,7 @@ hidden: true
 | Slot | Description |
 | --- | --- |
 {% for s in gen.all_slot_objects()|sort(attribute=sort_by) -%}
-| {{gen.link(s)}} | {{s.description|enshorten}} |
+| {{gen.link(s)}} | {{s.description | wordwrap(80, wrapstring='<br/>')}} |
 {% endfor %}
 
 
@@ -67,7 +67,7 @@ hidden: true
 | Enumeration | Description |
 | --- | --- |
 {% for e in gen.all_enum_objects()|sort(attribute=sort_by) -%}
-| {{gen.link(e)}} | {{e.description|enshorten}} |
+| {{gen.link(e)}} | {{e.description | wordwrap(80, wrapstring='<br/>')}} |
 {% endfor %}
 
 ```{toctree}
@@ -87,5 +87,5 @@ hidden: true
 | Type | Description |
 | --- | --- |
 {% for t in gen.all_type_objects()|sort(attribute=sort_by) -%}
-| {{gen.link(t)}} | {{t.description|enshorten}} |
+| {{gen.link(t)}} | {{t.description | wordwrap(80, wrapstring='<br/>')}} |
 {% endfor %}

docs/source/_templates/slot.md.jinja2

@@ -38,7 +38,7 @@ URI: {{ gen.uri_link(element) }}
 | Name | Description | Modifies Slot |
 | --- | --- | --- |
 {% for c in schemaview.get_classes_by_slot(element, include_induced=True) -%}
-{{ gen.link(c) }} | {{ schemaview.get_class(c).description }} | {% if c in schemaview.get_classes_modifying_slot(element) %} yes {% else %} no {% endif %} |
+{{ gen.link(c) }} | {{ schemaview.get_class(c).description|enshorten }} | {% if c in schemaview.get_classes_modifying_slot(element) %} yes {% else %} no {% endif %} |
 {% endfor %}
 
 {% endif %}

schemas/base.yaml

@@ -247,29 +247,32 @@ slots:
 
 enums:
     UsageTypes:
+        description: >-
+            This enumeration specifies the execution environment for the `Extractor`.
         permissible_values:
             cli:
                 description: >-
-                    Access the Extractor as a command line executable. The executable
+                    Access the `Extractor` as a command line executable. The executable
                     as well as the invocation syntax, parametrised using arguments,
                     shall be supplied in the `command` slot.
             python:
                 description: >-
-                    Access the Extractor as a Python function. The function should
+                    Access the `Extractor` as a Python function. The function should
                     be available when `import <setup>` is called, and should be
                     specified including relevant namespaces. The function signature,
                     parametrised using arguments, shall be supplied in the `command`
                     slot.
     UsageScope:
         description: >-
-            This enumeration allows the `Extractor->usage` to be described
-            in one of two modes, `meta-only` and `meta+data`, whereby
-            either a summary of file metadata, or the full file is returned
-            by the `Extractor`, respectively. In practice, this means that extractors
-            may have multiple defined usage modes for each scope and each
-            execution method. The default is to assume the 'worst case', i.e. that
-            the extractor returns as much of the data in the input file as
-            it supports, plus potentially additional analysis.
+            This enumeration specifies the scope of extraction performed by the `Extractor`.
+        comments:
+            - Currently allows the `Extractor->usage` to be described in one of two
+              modes, `meta-only` and `meta+data`.
+            - In practice, this means that extractors may have multiple defined usage
+              modes for each `UsageScope` and each `UsageType`.
+            - The default is to assume the 'worst case', i.e. that the `Extractor`
+              returns as much of the data in the input file as it supports, plus potentially
+              additional analysis.
         permissible_values:
             meta-only:
                 description: >-
@@ -309,11 +312,11 @@ enums:
         permissible_values:
             pip:
                 description: >-
-                    Install the Extractor using 'pip'. Will process `packages` using
+                    Install the `Extractor` using 'pip'. Will process `packages` using
                     `pip install` and `requirements` using `pip install -r`.
             conda:
                 description: >-
-                    Install the Extractor using 'conda'.
+                    Install the `Extractor` using 'conda'.
                 comments:
                     - Note that installation using `conda` is not yet supported by
                       the API.