[FSTORE-1551] Automatize API reference building & support aliases

.github/workflows/mkdocs-release.yml

@@ -92,7 +92,7 @@ jobs:
           working-directory: hopsworks-api/python
 
       - name: Install Python API dependencies
-        run: uv sync --extra dev --group docs --project hopsworks-api/python
+        run: uv sync --extra dev --project hopsworks-api/python
 
       - name: Install Python dependencies
         run: uv pip install -r requirements-docs.txt

.github/workflows/mkdocs-test.yml

@@ -53,7 +53,7 @@ jobs:
           working-directory: hopsworks-api/python
 
       - name: Install Python API dependencies
-        run: uv sync --extra dev --group docs --project hopsworks-api/python
+        run: uv sync --extra dev --project hopsworks-api/python
 
       - name: Install Python dependencies
         run: uv pip install -r requirements-docs.txt
@@ -64,7 +64,7 @@ jobs:
       - name: Check for broken links
         run: |
           # run the server
-          mkdocs serve > /dev/null 2>&1 &
+          mkdocs serve -q &
           SERVER_PID=$!
           echo "mk server in PID $SERVER_PID"
           # Give enough time for deployment (2min max)

docs/css/custom.css

@@ -171,31 +171,40 @@
 
 /*******************************************************/
 /* Fix z-index. */
-header.md-header {
-  z-index: 900 !important;
+.md-overlay {
+  z-index: 800 !important;
 }
 .md-sidebar {
-  z-index: 1000 !important;
+  z-index: 900 !important;
 }
-.md-overlay {
-  z-index: 950 !important;
+header.md-header {
+  z-index: 1000 !important;
 }
 .md-search__overlay {
   z-index: 1100 !important;
 }
-.md-search__form {
+.md-search__inner {
   z-index: 1200 !important;
 }
-.md-search__output {
-  z-index: 1100 !important;
-}
 
 /*******************************************************/
 /* Hide repo stats. */
 .md-source__fact--stars, .md-source__fact--forks {
   display: none;
 }
 
+/*******************************************************/
+/* Hide empty backlinks. */
+.info-backlinks:has(.doc-backlink-list:empty) {
+  display: none;
+}
+
+/*******************************************************/
+/* Hide symbol type labels from backlinks. */
+.doc-backlink-crumb .doc-symbol {
+  display: none;
+}
+
 /*******************************************************/
 /* Custom styles for syntax highlighting in signatures. */
 

docs/templates/python/material/attribute.html.jinja

@@ -1,12 +1,130 @@
-{% extends "_base/attribute.html.jinja" %}
+{#- Template for Python attributes.
 
-{% block heading scoped %}
-  {% block source_link scoped %}
-    {% if config.extra.link_source and attribute.source_link %}
-      <span style="float:right;font-size:.8rem;font-weight:400"><a href="{{ attribute.source_link }}">[source]</a></span>
+This template renders a Python attribute (or variable).
+This can be a module attribute or a class attribute.
+
+Context:
+  attribute (griffe.Attribute): The attribute 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 " + attribute.path) }}
+{% endblock logs %}
+
+<div class="doc doc-object doc-attribute">
+  {% with obj = attribute, html_id = attribute.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 attribute_name = attribute.path if show_full_path else attribute.name %}
+
+    {% if not root or config.show_root_heading %}
+      {% filter heading(
+          heading_level,
+          role="data" if attribute.parent.kind.value == "module" else "attr",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute.name),
+          skip_inventory=config.skip_local_inventory,
+        ) %}
+
+        {% block heading scoped %}
+          {#- Heading block.
+
+          This block renders the heading for the attribute.
+          -#}
+          {% block source_link scoped %}
+            {% if config.extra.link_source and attribute.source_link %}
+              <span style="float:right;font-size:.8rem;font-weight:400"><a href="{{ attribute.source_link }}">[source]</a></span>
+            {% endif %}
+          {% endblock source_link %}
+
+          {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
+          {% if config.heading and root %}
+            {{ config.heading }}
+          {% elif config.separate_signature %}
+            <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
+          {% else %}
+            {%+ filter highlight(language="python", inline=True) %}
+              {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %}
+              {% if config.show_attribute_values and attribute.value %} = {{ attribute.value }}{% endif %}
+            {% endfilter %}
+          {% endif %}
+        {% endblock heading %}
+
+        {% block labels scoped %}
+          {#- Labels block.
+
+          This block renders the labels for the attribute.
+          -#}
+          {% with labels = attribute.labels %}
+            {% include "labels.html.jinja" with context %}
+          {% endwith %}
+        {% endblock labels %}
+
+      {% endfilter %}
+
+      {% block signature scoped %}
+        {#- Signature block.
+
+        This block renders the signature for the attribute.
+        -#}
+        {% if config.separate_signature and (attribute.value or attribute.annotation) %}
+          {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs, show_value=config.show_attribute_values) %}
+            {{ attribute.name }}
+          {% endfilter %}
+        {% endif %}
+      {% endblock signature %}
+
+    {% else %}
+
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="data" if attribute.parent.kind.value == "module" else "attr",
+            id=html_id,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name),
+            hidden=True,
+            skip_inventory=config.skip_local_inventory,
+          ) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
     {% endif %}
-  {% endblock source_link %}
 
-  {{ super() }}
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% block contents scoped %}
+        {#- Contents block.
+
+        This block renders the contents of the attribute.
+        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 attribute.
+          -#}
+          {% with docstring_sections = attribute.docstring.parsed %}
+            {% include "docstring.html.jinja" with context %}
+          {% endwith %}
+        {% endblock docstring %}
+      {% endblock contents %}
+    </div>
 
-{% endblock heading %}
+  {% endwith %}
+</div>

docs/templates/python/material/backlinks.html.jinja

@@ -0,0 +1,25 @@
+{#- Template for backlinks.
+
+This template renders backlinks.
+
+Context:
+  backlinks (Mapping[str, Iterable[str]]): The backlinks to render.
+  config (dict): The configuration options.
+  verbose_type (Mapping[str, str]): The verbose backlink types.
+  default_crumb (BacklinkCrumb): A default, empty crumb.
+-#}
+
+{% macro render_crumb(crumb) %}
+  <span class="doc doc-backlink-crumb">
+    {% if crumb.url and crumb.title %}
+      <a href="{{ crumb.url }}"><code>{{ crumb.parent.title | replace("&nbsp;", "") | safe }}.{{ crumb.title | replace("&nbsp;", "") | safe }}</code></a>
+    {% endif %}
+  </span>
+{% endmacro %}
+
+
+{%- for backlink in backlinks["returned-by"] | sort(attribute="crumbs") -%}
+  <li class="doc doc-backlink">
+    {{ render_crumb(backlink.crumbs[-1]) }}
+  </li>
+{%- endfor -%}