Autogenerate API documentation (#80)

* Autogenerated API documentation

* Add step to include acquire-python docstrings in docs build

* Autogenerated API documentation (#10)

* Autogenerated API documentation

* Add step to include acquire-python docstrings in docs build

* Reorganize mkdocstrings options

Adds two custom templates to remove private module attributes from the rendering.

* Improve class and methods display

Change font sizing and spacing to better delimit module objects

* Do not show submodules

This was creating a duplication of members because of the acquire.acquire module.

* Fix acquire-python path

* Fix deployment

* Reduce method heading font size

* Remove init docstrings from class descriptions

* Change class and function label colors, spell out object type

.github/workflows/deploy_docs.yml

@@ -21,25 +21,44 @@ jobs:
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
 
-      - uses: actions/checkout@v3
+      - name: Clone acquire-docs repo
+        uses: actions/checkout@v4
+        with:
+          path: acquire-docs  # place in a named directory
+
       - uses: actions/setup-python@v4
         with:
           python-version: '3.10'
-      - run: pip install -r requirements.txt
+      - run: pip install -r acquire-docs/requirements.txt
 
       - name: Generate downloadable scripts
         run: |
+          cd acquire-docs
           bash .github/workflows/convert.sh
 
+      - name: Clone acquire-python repo
+        uses: actions/checkout@v4
+        with:
+          path: acquire-python  # place in a named directory
+          repository: acquire-project/acquire-python
+
+      - name: Install acquire-python  # For collecting the API reference
+        run: |
+          cd acquire-python
+          git submodule update --init --recursive
+          python -m pip install -e .
+
       - name: Build website
         run: |
+          cd acquire-docs
           mkdocs build
 
       - name: Deploy docs
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: site
+          # external_repository: acquire/acquire-docs.github.io
+          publish_dir: acquire-docs/site
           publish_branch: gh-pages
           destination_dir: dev
           # cname: acquire.org

docs/_templates/python/material/children-no-attrs.html.jinja

@@ -0,0 +1,172 @@
+{#- Template for members (children) of an object.
+
+This template iterates on members of a given object and renders them.
+It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
+
+Context:
+  obj (griffe.Object): The object to render.
+  config (dict): The configuration options.
+  root_members (bool): Whether the object is the root object.
+  heading_level (int): The HTML heading level to use.
+-#}
+
+{% if obj.all_members %}
+  {% block logs scoped %}
+    {#- Logging block.
+    
+    This block can be used to log debug messages, deprecation messages, warnings, etc.
+    -#}
+    {{ log.debug("Rendering children of " + obj.path) }}
+  {% endblock logs %}
+
+  <div class="doc doc-children">
+
+    {% if root_members %}
+      {% set members_list = config.members %}
+    {% else %}
+      {% set members_list = none %}
+    {% endif %}
+
+    {% if config.group_by_category %}
+
+      {% with %}
+
+        {% if config.show_category_heading %}
+          {% set extra_level = 1 %}
+        {% else %}
+          {% set extra_level = 0 %}
+        {% endif %}
+
+        {# {% with attributes = obj.attributes|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if attributes %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for attribute in attributes|order_members(config.members_order, members_list) %}
+                {% if members_list is not none or (not attribute.is_imported or attribute.is_public) %}
+                  {% include attribute|get_template with context %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %} #}
+
+        {% with classes = obj.classes|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if classes %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for class in classes|order_members(config.members_order, members_list) %}
+                {% if members_list is not none or (not class.is_imported or class.is_public) %}
+                  {% include class|get_template with context %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %}
+
+        {% with functions = obj.functions|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if functions %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for function in functions|order_members(config.members_order, members_list) %}
+                {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
+                  {% if members_list is not none or (not function.is_imported or function.is_public) %}
+                    {% include function|get_template with context %}
+                  {% endif %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %}
+
+        {% if config.show_submodules %}
+          {% with modules = obj.modules|filter_objects(
+              filters=config.filters,
+              members_list=members_list,
+              inherited_members=config.inherited_members,
+              keep_no_docstrings=config.show_if_no_docstring,
+            ) %}
+            {% if modules %}
+              {% if config.show_category_heading %}
+                {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
+              {% endif %}
+              {% with heading_level = heading_level + extra_level %}
+                {% for module in modules|order_members(config.members_order.alphabetical, members_list) %}
+                  {% if members_list is not none or (not module.is_alias or module.is_public) %}
+                    {% include module|get_template with context %}
+                  {% endif %}
+                {% endfor %}
+              {% endwith %}
+            {% endif %}
+          {% endwith %}
+        {% endif %}
+
+      {% endwith %}
+
+    {% else %}
+
+      {% for child in obj.all_members
+          |filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+            )
+          |order_members(config.members_order, members_list)
+        %}
+
+        {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
+
+          {% if members_list is not none or child.is_public %}
+            {% if child.is_attribute %}
+              {% with attribute = child %}
+                {% include attribute|get_template with context %}
+              {% endwith %}
+
+            {% elif child.is_class %}
+              {% with class = child %}
+                {% include class|get_template with context %}
+              {% endwith %}
+
+            {% elif child.is_function %}
+              {% with function = child %}
+                {% include function|get_template with context %}
+              {% endwith %}
+
+            {% elif child.is_module and config.show_submodules %}
+              {% with module = child %}
+                {% include module|get_template with context %}
+              {% endwith %}
+
+            {% endif %}
+          {% endif %}
+
+        {% endif %}
+
+      {% endfor %}
+
+    {% endif %}
+
+  </div>
+
+{% endif %}

docs/_templates/python/material/module.html.jinja

@@ -0,0 +1,113 @@
+{#- Template for Python modules.
+
+This template renders a Python module.
+
+Context:
+  module (griffe.Module): The module to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering " + module.path) }}
+{% endblock logs %}
+
+<div class="doc doc-object doc-module">
+  {% with obj = module, html_id = module.path %}
+
+    {% if root %}
+      {% set show_full_path = config.show_root_full_path %}
+      {% set root_members = True %}
+    {% elif root_members %}
+      {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+      {% set root_members = False %}
+    {% else %}
+      {% set show_full_path = config.show_object_full_path %}
+    {% endif %}
+
+    {% set module_name = module.path if show_full_path else module.name %}
+
+    {% if not root or config.show_root_heading %}
+      {% filter heading(
+          heading_level,
+          role="module",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + module.name,
+        ) %}
+
+        {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the module.
+          -#}
+          {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>{% endif %}
+          {% if config.separate_signature %}
+            <span class="doc doc-object-name doc-module-name">{{ module_name }}</span>
+          {% else %}
+            <code>{{ module_name }}</code>
+          {% endif %}
+        {% endblock heading %}
+
+        {% block labels scoped %}
+          {#- Labels block.
+          
+          This block renders the labels for the module.
+          -#}
+          {% with labels = module.labels %}
+            {% include "labels"|get_template with context %}
+          {% endwith %}
+        {% endblock labels %}
+
+      {% endfilter %}
+
+    {% else %}
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="module",
+            id=html_id,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + module.name,
+            hidden=True,
+          ) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
+    {% endif %}
+
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% block contents scoped %}
+        {#- Contents block.
+        
+        This block renders the contents of the module.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
+        {% block docstring scoped %}
+          {#- Docstring block.
+          
+          This block renders the docstring for the module.
+          -#}
+          {% with docstring_sections = module.docstring.parsed %}
+            {% include "docstring"|get_template with context %}
+          {% endwith %}
+        {% endblock docstring %}
+
+        {% block children scoped %}
+          {#- Children block.
+          
+          This block renders the children (members) of the module.
+          -#}
+          {% set root = False %}
+          {% set heading_level = heading_level + 1 %}
+          {% include "children-no-attrs"|get_template with context %}
+        {% endblock children %}
+      {% endblock contents %}
+    </div>
+
+  {% endwith %}
+</div>