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

docs/css/custom.css

@@ -171,24 +171,21 @@
 
 /*******************************************************/
 /* 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. */

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

@@ -1,6 +1,22 @@
 {% extends "_base/class.html.jinja" %}
 
 {% block heading scoped %}
+  {% block alias_anchors scoped %}
+    {% if class.extra.hopsworks_apigen and class.extra.hopsworks_apigen.aliases %}
+      {% for alias in class.extra.hopsworks_apigen.aliases -%}
+        {%- set alias_id = alias.target_module + "." + alias.alias_name -%}
+        {% filter heading(
+          9,
+          role="class",
+          id=alias_id,
+          class="doc doc-heading",
+          hidden=true,
+          skip_inventory=config.skip_local_inventory,
+        ) -%}{%- endfilter %}
+      {%- endfor %}
+    {% endif %}
+  {% endblock alias_anchors %}
+
   {% block source_link scoped %}
     {% if config.extra.link_source and class.source_link %}
       <span style="float:right;font-size:.8rem;font-weight:400"><a href="{{ class.source_link }}">[source]</a></span>
@@ -10,3 +26,22 @@
   {{ super() }}
 
 {% endblock heading %}
+
+{% block contents scoped %}
+  {% block aliases scoped %}
+    {% if class.extra.hopsworks_apigen and class.extra.hopsworks_apigen.aliases %}
+      {%- set public_aliases = class.extra.hopsworks_apigen.aliases | selectattr("is_public") | list -%}
+      {% if public_aliases and public_aliases[1:] %}
+        <p class="doc doc-class-aliases">
+          Aliases: {% for alias in public_aliases[1:] -%}
+            {%- set fullpath = alias.target_module + "." + alias.alias_name -%}
+            <a href="#{{fullpath}}"><code>{{fullpath}}</code></a>
+            {%- if not loop.last %}, {% endif %}
+          {%- endfor %}
+        </p>
+      {% endif %}
+    {% endif %}
+  {% endblock aliases %}
+
+  {{ super() }}
+{% endblock contents %}

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

@@ -1,6 +1,35 @@
 {% extends "_base/function.html.jinja" %}
 
 {% block heading scoped %}
+  {% block alias_anchors scoped %}
+    {% if function.extra.hopsworks_apigen and function.extra.hopsworks_apigen.aliases %}
+      {% for alias in function.extra.hopsworks_apigen.aliases -%}
+        {%- set alias_id = alias.target_module + "." + alias.alias_name -%}
+        {% filter heading(
+          9,
+          role="function",
+          id=alias_id,
+          class="doc doc-heading",
+          hidden=true,
+          skip_inventory=config.skip_local_inventory,
+        ) -%}{%- endfilter %}
+      {%- endfor %}
+    {% endif %}
+    {% if function.parent and function.parent.extra.hopsworks_apigen and function.parent.extra.hopsworks_apigen.aliases %}
+      {% for alias in function.parent.extra.hopsworks_apigen.aliases -%}
+        {%- set alias_id = alias.target_module + "." + alias.alias_name + "." + function.name -%}
+        {% filter heading(
+          9,
+          role="function",
+          id=alias_id,
+          class="doc doc-heading",
+          hidden=true,
+          skip_inventory=config.skip_local_inventory,
+        ) -%}{%- endfilter %}
+      {%- endfor %}
+    {% endif %}
+  {% endblock alias_anchors %}
+
   {% block source_link scoped %}
     {% if config.extra.link_source and function.source_link %}
       <span style="float:right;font-size:.8rem;font-weight:400"><a href="{{ function.source_link }}">[source]</a></span>
@@ -10,3 +39,22 @@
   {{ super() }}
 
 {% endblock heading %}
+
+{% block contents scoped %}
+  {% block aliases scoped %}
+    {% if function.extra.hopsworks_apigen and function.extra.hopsworks_apigen.aliases %}
+      {%- set public_aliases = function.extra.hopsworks_apigen.aliases | selectattr("is_public") | list -%}
+      {% if public_aliases and public_aliases[1:] %}
+        <p class="doc doc-class-aliases">
+          Aliases: {% for alias in public_aliases[1:] -%}
+            {%- set fullpath = alias.target_module + "." + alias.alias_name -%}
+            <a href="#{{fullpath}}"><code>{{fullpath}}</code></a>
+            {%- if not loop.last %}, {% endif %}
+          {%- endfor %}
+        </p>
+      {% endif %}
+    {% endif %}
+  {% endblock aliases %}
+
+  {{ super() }}
+{% endblock contents %}

mkdocs.yml

@@ -264,7 +264,7 @@ nav:
               - Access Audit Logs: setup_installation/admin/audit/audit-logs.md
               - Export Audit Logs: setup_installation/admin/audit/export-audit-logs.md
       - ArrowFlight Server with DuckDB: setup_installation/common/arrow_flight_duckdb.md
-  - Python API: "!import https://github.com/logicalclocks/hopsworks-api?branch=main"
+  - Python API: python-api
   - Java API: javadoc
   - Community ↗: https://community.hopsworks.ai/
 
@@ -333,7 +333,14 @@ plugins:
       minify_js: true
   - mike:
       canonical_version: latest
-  - multirepo
+  - hopsworks-apigen:
+      modules:
+        - hopsworks_common
+        - hsfs
+        - hsml
+        - hopsworks
+      nav_section_title: Python API
+      api_root_uri: python-api
   - mkdocstrings:
       custom_templates: docs/templates
       handlers:
@@ -346,11 +353,15 @@ plugins:
             signature_crossrefs: true
             show_symbol_type_heading: true
             show_symbol_type_toc: true
+            members_order: source
             show_source: false
             docstring_section_style: spacy
             annotations_path: source
+            filters: public
             extra:
               link_source: true
+            extensions:
+              - hopsworks_apigen.mkdocs
           inventories:
             - https://docs.python.org/3/objects.inv
             - https://pandas.pydata.org/docs/objects.inv

requirements-docs.txt

@@ -4,7 +4,8 @@ mike==2.1.3
 markdown==3.9
 pymdown-extensions==10.17.2
 mkdocs-minify-plugin>=0.2.0
-mkdocs-multirepo-plugin==0.8.3
+hopsworks-apigen@git+https://github.com/aversey/hopsworks-aliases.git
 mkdocstrings[python]==1.0.0
 mkdocstrings-python==2.0.1
+ruff==0.15.0
 linkchecker