-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Feature / API documentation update (#472)
* Update model API doc comments * Update Sphinx config for AutoAPI * Custom templates for modules and classes in AutoAPI * Use handwritten RST for top level reference pages * Do not flat-pack modules in docgen-ctrl (this is now handled correctly in Sphinx) * Qualify namespaces for types in the code generator for python docs * Documentation theme updates * Fix a bad doc reference in the runtime exception classes * Fix doc layout for DECIMAL precision / scale info * Fix Sphinx warnings * Flatpack the runtime metadata module for documentation * Update the code generator to handle type scoping for both regular Python and Sphinx AutoAPI * Fix handling nested types in the generator when not running with doc_semantics * Work around for scope resolution of one nested type (that cannot be solved in the regular structure) * Doc updates in model_api module * Exclude declare_ functions from public docs * Doc updates in static_api module * Doc updates in the launch module * Add doc comments for top level constants in the api module * Top level doc comments for public modules * Minor tidy up in conf.py * Update function references in @see annotations for metadata.proto * Update for translating @see comments in the Python generator * Remove chapter numbers from paths in tutorial files * Fix references to class methods * Fix references to class attributes * Update attribute references defined in code * Fix generating attribute references from @see annotations * Update type references for some non-TRAC types in doc comments * Update line numbers in modelling tutorials after header changes * Update line numbers in app dev tutorials after header changes * Use release instead of version in top level headline (to change in 0.8) * Rename metadata listing and service listing references * Fix width of code blocks in modelling tutorials * Fix width of code blocks in app dev tutorials * Fix headings in introduction * Use chapter headings in tutorials * Table headers in dark mode * Use finTRAC CSS for docs styling * Fix links in the main README file
- Loading branch information
1 parent
68c5129
commit 221c6d4
Showing
36 changed files
with
1,308 additions
and
553 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,120 @@ | ||
{% if obj.display %} | ||
{% if is_own_page %} | ||
.. raw:: html | ||
|
||
{{ '<span class="code">' }} | ||
|
||
{{ obj.name }} | ||
{{ "=" * obj.name | length }} | ||
|
||
.. raw:: html | ||
|
||
{{ '</span>' }} | ||
|
||
{% endif %} | ||
{% set visible_children = obj.children|selectattr("display")|list %} | ||
{% set own_page_children = visible_children|selectattr("type", "in", own_page_types)|list %} | ||
{% if is_own_page and own_page_children %} | ||
.. toctree:: | ||
:hidden: | ||
|
||
{% for child in own_page_children %} | ||
{{ child.include_path }} | ||
{% endfor %} | ||
|
||
{% endif %} | ||
|
||
{% set show_obj_args = False %} | ||
|
||
.. py:{{ obj.type }}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}{% if show_obj_args %}({{ obj.args }}){% endif %} | ||
{% for (args, return_annotation) in obj.overloads %} | ||
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %} | ||
|
||
{% endfor %} | ||
|
||
{% if is_own_page %} | ||
.. py:currentmodule:: {{ obj.id.replace('.' + obj.name, '') }} | ||
{% endif %} | ||
|
||
{% if obj.bases %} | ||
{% if "show-inheritance" in autoapi_options %} | ||
|
||
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %} | ||
{% endif %} | ||
|
||
|
||
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %} | ||
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }} | ||
:parts: 1 | ||
{% if "private-members" in autoapi_options %} | ||
:private-bases: | ||
{% endif %} | ||
|
||
{% endif %} | ||
{% endif %} | ||
{% if obj.docstring %} | ||
|
||
{{ obj.docstring|indent(3) }} | ||
{% endif %} | ||
{% for obj_item in visible_children %} | ||
{% if obj_item.type not in own_page_types %} | ||
|
||
{{ obj_item.render()|indent(3) }} | ||
{% endif %} | ||
{% endfor %} | ||
{% if is_own_page and own_page_children %} | ||
{% set visible_attributes = own_page_children|selectattr("type", "equalto", "attribute")|list %} | ||
{% if visible_attributes %} | ||
Attributes | ||
---------- | ||
|
||
.. autoapisummary:: | ||
|
||
{% for attribute in visible_attributes %} | ||
{{ attribute.name }} | ||
{% endfor %} | ||
|
||
|
||
{% endif %} | ||
{% set visible_exceptions = own_page_children|selectattr("type", "equalto", "exception")|list %} | ||
{% if visible_exceptions %} | ||
Exceptions | ||
---------- | ||
|
||
.. autoapisummary:: | ||
|
||
{% for exception in visible_exceptions %} | ||
{{ exception.id }} | ||
{% endfor %} | ||
|
||
|
||
{% endif %} | ||
{% set visible_classes = own_page_children|selectattr("type", "equalto", "class")|list %} | ||
{% if visible_classes %} | ||
Classes | ||
------- | ||
|
||
.. autoapisummary:: | ||
|
||
{% for klass in visible_classes %} | ||
{{ klass.id }} | ||
{% endfor %} | ||
|
||
|
||
{% endif %} | ||
{% set visible_methods = own_page_children|selectattr("type", "equalto", "method")|list %} | ||
{% if visible_methods %} | ||
Methods | ||
------- | ||
|
||
.. autoapisummary:: | ||
|
||
{% for method in visible_methods %} | ||
{{ method.name }} | ||
{% endfor %} | ||
|
||
|
||
{% endif %} | ||
{% endif %} | ||
{% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
{% if obj.display %} | ||
{% if is_own_page %} | ||
{{ obj.id }} | ||
{{ "=" * obj.id | length }} | ||
|
||
{% endif %} | ||
.. py:{{ obj.type }}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.name }}{% endif %} | ||
:canonical: {{ obj.id }} | ||
{% if obj.annotation is not none %} | ||
:type: {% if obj.annotation %} {{ obj.annotation }}{% endif %} | ||
{% endif %} | ||
{% if obj.value is not none %} | ||
{% if obj.value.splitlines()|count > 1 %} | ||
:value: Multiline-String | ||
|
||
.. raw:: html | ||
|
||
<details><summary>Show Value</summary> | ||
|
||
.. code-block:: python | ||
{{ obj.value|indent(width=6,blank=true) }} | ||
.. raw:: html | ||
|
||
</details> | ||
|
||
{% else %} | ||
:value: {{ obj.value|truncate(100) }} | ||
{% endif %} | ||
{% endif %} | ||
|
||
{% if obj.docstring %} | ||
|
||
{{ obj.docstring|indent(3) }} | ||
{% endif %} | ||
{% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
{% if obj.display %} | ||
{% if ":display: False" not in obj.docstring %} | ||
{% if is_own_page %} | ||
{{ obj.id }} | ||
{{ "=" * obj.id | length }} | ||
|
||
{% endif %} | ||
.. py:function:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %} | ||
{% for (args, return_annotation) in obj.overloads %} | ||
|
||
{%+ if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %} | ||
{% endfor %} | ||
{% for property in obj.properties %} | ||
|
||
:{{ property }}: | ||
{% endfor %} | ||
|
||
{% if obj.docstring %} | ||
|
||
{{ obj.docstring|indent(3) }} | ||
{% endif %} | ||
{% endif %} | ||
{% endif %} |
Oops, something went wrong.