diff --git a/.github/workflows/mkdocs-release.yml b/.github/workflows/mkdocs-release.yml index 63ffc0f23..4a751fc7d 100644 --- a/.github/workflows/mkdocs-release.yml +++ b/.github/workflows/mkdocs-release.yml @@ -59,7 +59,7 @@ jobs: - name: Checkout the API repo uses: actions/checkout@v4 with: - repository: logicalclocks/hopsworks-api + repository: aversey/hopsworks-api ref: ${{ env.BRANCH }} path: hopsworks-api diff --git a/.github/workflows/mkdocs-test.yml b/.github/workflows/mkdocs-test.yml index fa2c942f1..93a8527f6 100644 --- a/.github/workflows/mkdocs-test.yml +++ b/.github/workflows/mkdocs-test.yml @@ -15,7 +15,7 @@ jobs: - name: Checkout the API repo uses: actions/checkout@v4 with: - repository: logicalclocks/hopsworks-api + repository: aversey/hopsworks-api ref: ${{ github.base_ref }} path: hopsworks-api diff --git a/docs/css/custom.css b/docs/css/custom.css index c09c2be37..26f7a273c 100644 --- a/docs/css/custom.css +++ b/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. */ @@ -196,6 +193,18 @@ header.md-header { 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. */ diff --git a/docs/templates/python/material/attribute.html.jinja b/docs/templates/python/material/attribute.html.jinja index 97eb8ebe3..f5d1fe083 100644 --- a/docs/templates/python/material/attribute.html.jinja +++ b/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 %} - [source] +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 %} + +
+ {% 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=(' '|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 %} + [source] + {% endif %} + {% endblock source_link %} + + {% if config.show_symbol_type_heading %}{% endif %} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ attribute_name }} + {% 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=(' '|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() }} +
+ {% 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 %} +
-{% endblock heading %} + {% endwith %} +
diff --git a/docs/templates/python/material/backlinks.html.jinja b/docs/templates/python/material/backlinks.html.jinja new file mode 100644 index 000000000..ecbfa2cac --- /dev/null +++ b/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) %} + + {% if crumb.url and crumb.title %} + {{ crumb.parent.title | replace(" ", "") | safe }}.{{ crumb.title | replace(" ", "") | safe }} + {% endif %} + +{% endmacro %} + + +{%- for backlink in backlinks["returned-by"] | sort(attribute="crumbs") -%} + +{%- endfor -%} diff --git a/docs/templates/python/material/class.html.jinja b/docs/templates/python/material/class.html.jinja index 40687fccf..ed2028908 100644 --- a/docs/templates/python/material/class.html.jinja +++ b/docs/templates/python/material/class.html.jinja @@ -1,12 +1,350 @@ -{% extends "_base/class.html.jinja" %} +{#- Template for Python classes. -{% block heading scoped %} - {% block source_link scoped %} - {% if config.extra.link_source and class.source_link %} - [source] +This template renders a Python class. + +Context: + class (griffe.Class): The class 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 " + class.path) }} +{% endblock logs %} + +{% import "language.html.jinja" as lang with context %} +{#- Language module providing the `t` translation method. -#} + +
+ {% with obj = class, html_id = class.path, all_members = class.all_members %} + + {% 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 %} - {% endblock source_link %} - {{ super() }} + {% set class_name = class.path if show_full_path else class.name %} + + {% if not root or config.show_root_heading %} + {% filter heading( + heading_level, + role="class", + id=html_id, + class="doc doc-heading", + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name), + skip_inventory=config.skip_local_inventory, + ) %} + + {% block heading scoped %} + {#- Heading block. + + This block renders the heading for the class. + -#} + {% 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 %} + [source] + {% endif %} + {% endblock source_link %} + + {% if config.show_symbol_type_heading %}{% endif %} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ class_name }} + {% elif config.merge_init_into_class and "__init__" in all_members %} + {% with function = all_members["__init__"] %} + {%+ filter highlight(language="python", inline=True) %} + {{ class_name -}} + {%- with obj = function -%} + {%- include "type_parameters.html.jinja" with context -%} + {%- endwith -%} + {%- include "signature.html.jinja" with context -%} + {% endfilter %} + {% endwith %} + {% else %} + {# TODO: Maybe render type parameters here. #} + {{ class_name }} + {% endif %} + {% endblock heading %} + + {% block labels scoped %} + {#- Labels block. + + This block renders the labels for the class. + -#} + {% with labels = class.labels %} + {% include "labels.html.jinja" with context %} + {% endwith %} + {% endblock labels %} + + {% endfilter %} + + {% block signature scoped %} + {#- Signature block. + + This block renders the signature for the class. + Overloads of the `__init__` method are rendered if `merge_init_into_class` is enabled. + The actual `__init__` method signature is only rendered if `separate_signature` is also enabled. + + If the class is generic, but the `__init__` method isn't or `merge_init_into_class` is disabled, + the class signature is rendered if `separate_signature` and `show_signature_type_parameters` are enabled. + + If the `__init__` method or any overloads are generic, they are rendered as methods if + `merge_init_into_class`, `separate_signature` and `show_signature_type_parameters` are enabled. + -#} + {% if config.merge_init_into_class and "__init__" in all_members %} + {% with function = all_members["__init__"] %} + {% if function.overloads and config.show_overloads %} +
+ {% for overload in function.overloads %} + {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %} + {{ class.name }} + {% endfilter %} + {% endfor %} +
+ {% endif %} + {% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %} + {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} + {{ class.name }} + {% endfilter %} + {% endif %} + {% endwith %} + {% endif %} + {% endblock signature %} + + {% else %} + {% if config.show_root_toc_entry %} + {% filter heading(heading_level, + role="class", + id=html_id, + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name), + hidden=True, + skip_inventory=config.skip_local_inventory, + ) %} + {% endfilter %} + {% endif %} + {% set heading_level = heading_level - 1 %} + {% endif %} + +
+ {% block contents scoped %} + {#- Contents block. + + This block renders the contents of the class. + It contains other blocks that users can override. + Overriding the contents block allows to rearrange the order of the blocks. + -#} + {% block bases scoped %} + {#- Class bases block. + + This block renders the bases for the class. + -#} + {% if config.show_bases and class.bases %} +

+ Bases: {% for expression in class.bases -%} + + {%- with backlink_type = "subclassed-by" -%} + {%- include "expression.html.jinja" with context -%} + {%- endwith -%} + {% if not loop.last %}, {% endif %} + {% endfor -%} +

+ {% endif %} + {% endblock bases %} + + {% block inheritance_diagram scoped %} + {#- Inheritance diagram block. + + This block renders the inheritance diagram for the class, + using Mermaid syntax and a bit of JavaScript to make the nodes clickable, + linking to the corresponding class documentation. + -#} + {% if config.show_inheritance_diagram and class.bases %} + {% macro edges(class) %} + {% for base in class.resolved_bases %} + {{ base.path }} --> {{ class.path }} + {{ edges(base) }} + {% endfor %} + {% endmacro %} +
+ + {% for base in class.mro() %} + + {% endfor %} +
+

+              flowchart {{ config.inheritance_diagram_direction }}
+              {{ class.path }}[{{ class.name }}]
+              {% for base in class.mro() %}
+              {{ base.path }}[{{ base.name }}]
+              {% endfor %}
+
+              {{ edges(class) | safe }}
+
+              click {{ class.path }} href "" "{{ class.path }}"
+              {% for base in class.mro() %}
+              click {{ base.path }} href "" "{{ base.path }}"
+              {% endfor %}
+            
+ + {% endif %} + {% endblock inheritance_diagram %} + + {% block docstring scoped %} + {#- Docstring block. + + This block renders the docstring for the class. + -#} + {% with docstring_sections = class.docstring.parsed %} + {% include "docstring.html.jinja" with context %} + {% endwith %} + {% if config.merge_init_into_class %} + {# We don't want to merge the inherited `__init__` method docstring into the class docstring #} + {# if such inherited method was not selected through `inherited_members`. #} + {% with check_members = all_members if (config.inherited_members is true or (config.inherited_members is iterable and "__init__" in config.inherited_members)) else class.members %} + {% if "__init__" in check_members and check_members["__init__"].has_docstring %} + {% with function = check_members["__init__"] %} + {% with obj = function, docstring_sections = function.docstring.parsed %} + {% include "docstring.html.jinja" with context %} + {% endwith %} + {% endwith %} + {% endif %} + {% endwith %} + {% endif %} + {% endblock docstring %} + + {% 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:] %} +

+ For backwards compatibility + {% set fullpath = public_aliases[0].target_module + "." + public_aliases[0].alias_name %} + {{fullpath}} + is still available as + {% for alias in public_aliases[1:] -%} + {%- set fullpath = alias.target_module + "." + alias.alias_name -%} + {{fullpath}} + {%- if not loop.last %}, {% endif %} + {%- endfor %}. + {% if public_aliases[2:] %} + The use of these aliases is discouraged as they are to be deprecated. + {% else %} + The use of this alias is discouraged as it is to be deprecated. + {% endif %} +

+ {% endif %} + {% endif %} + {% endblock aliases %} + + {% block backlinks scoped %} + {% if class.extra.hopsworks_apigen and class.extra.hopsworks_apigen.aliases %} + + {% endif %} + {% endblock backlinks %} + + {% block summary scoped %} + {#- Summary block. + + This block renders auto-summaries for classes, methods, and attributes. + -#} + {% include "summary.html.jinja" with context %} + {% endblock summary %} + + {% block source scoped %} + {#- Source block. + + This block renders the source code for the class. + -#} + {% if config.show_source %} + {% if config.merge_init_into_class %} + {% if "__init__" in all_members and all_members["__init__"].source %} + {% with init = all_members["__init__"] %} +
+ {{ lang.t("Source code in") }} + {%- if init.relative_filepath.is_absolute() -%} + {{ init.relative_package_filepath }} + {%- else -%} + {{ init.relative_filepath }} + {%- endif -%} + + {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }} +
+ {% endwith %} + {% endif %} + {% elif class.source %} +
+ {{ lang.t("Source code in") }} + {%- if class.relative_filepath.is_absolute() -%} + {{ class.relative_package_filepath }} + {%- else -%} + {{ class.relative_filepath }} + {%- endif -%} + + {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }} +
+ {% endif %} + {% endif %} + {% endblock source %} + + {% block children scoped %} + {#- Children block. + + This block renders the children (members) of the class. + -#} + {% set root = False %} + {% set heading_level = heading_level + 1 %} + {% include "children.html.jinja" with context %} + {% endblock children %} + {% endblock contents %} +
-{% endblock heading %} + {% endwith %} +
diff --git a/docs/templates/python/material/function.html.jinja b/docs/templates/python/material/function.html.jinja index 7d621a25e..b2f67aee9 100644 --- a/docs/templates/python/material/function.html.jinja +++ b/docs/templates/python/material/function.html.jinja @@ -1,12 +1,219 @@ -{% extends "_base/function.html.jinja" %} +{#- Template for Python functions. -{% block heading scoped %} - {% block source_link scoped %} - {% if config.extra.link_source and function.source_link %} - [source] +This template renders a Python function or method. + +Context: + function (griffe.Function): The function 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 " + function.path) }} +{% endblock logs %} + +{% import "language.html.jinja" as lang with context %} +{#- Language module providing the `t` translation method. -#} + +
+ {% with obj = function, html_id = function.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 %} - {% endblock source_link %} - {{ super() }} + {% set function_name = function.path if show_full_path else function.name %} + {#- Brief or full function name depending on configuration. -#} + {% set symbol_type = "method" if function.parent.is_class else "function" %} + {#- Symbol type: method when parent is a class, function otherwise. -#} + + {% if not root or config.show_root_heading %} + {% filter heading( + heading_level, + role="function", + id=html_id, + class="doc doc-heading", + toc_label=((' ')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name), + skip_inventory=config.skip_local_inventory, + ) %} + + {% block heading scoped %} + {#- Heading block. + + This block renders the heading for the function. + -#} + {% 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 %} + [source] + {% endif %} + {% endblock source_link %} + + {% if config.show_symbol_type_heading %}{% endif %} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ function_name }} + {% else %} + {%+ filter highlight(language="python", inline=True) -%} + {{ function_name }} + {%- include "type_parameters.html.jinja" with context -%} + {%- include "signature.html.jinja" with context -%} + {%- endfilter %} + {% endif %} + {% endblock heading %} + + {% block labels scoped %} + {#- Labels block. + + This block renders the labels for the function. + -#} + {% with labels = function.labels %} + {% include "labels.html.jinja" with context %} + {% endwith %} + {% endblock labels %} + + {% endfilter %} + + {% block signature scoped %} + {#- Signature block. + + This block renders the signature for the function, + as well as its overloaded signatures if any. + -#} + {% if function.overloads and config.show_overloads %} +
+ {% for overload in function.overloads %} + {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %} + {{ overload.name }} + {% endfilter %} + {% endfor %} +
+ {% endif %} + {% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %} + {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} + {{ function.name }} + {% endfilter %} + {% endif %} + {% endblock signature %} + + {% else %} + + {% if config.show_root_toc_entry %} + {% filter heading( + heading_level, + role="function", + id=html_id, + toc_label=((' ')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name), + hidden=True, + skip_inventory=config.skip_local_inventory, + ) %} + {% endfilter %} + {% endif %} + {% set heading_level = heading_level - 1 %} + {% endif %} + +
+ {% block contents scoped %} + {#- Contents block. + + This block renders the contents of the function. + It contains other blocks that users can override. + Overriding the contents block allows to rearrange the order of the blocks. + -#} + {% 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:] %} +

+ For backwards compatibility + {% set fullpath = public_aliases[0].target_module + "." + public_aliases[0].alias_name %} + {{fullpath}} + is still available as + {% for alias in public_aliases[1:] -%} + {%- set fullpath = alias.target_module + "." + alias.alias_name -%} + {{fullpath}} + {%- if not loop.last %}, {% endif %} + {%- endfor %}. + {% if public_aliases[2:] %} + The use of these aliases is discouraged as they are to be deprecated. + {% else %} + The use of this alias is discouraged as it is to be deprecated. + {% endif %} +

+ {% endif %} + {% endif %} + {% endblock aliases %} + + {% block docstring scoped %} + {#- Docstring block. + + This block renders the docstring for the function. + -#} + {% with docstring_sections = function.docstring.parsed %} + {% include "docstring.html.jinja" with context %} + {% endwith %} + {% endblock docstring %} + + {% block source scoped %} + {#- Source block. + + This block renders the source code for the function. + -#} + {% if config.show_source and function.source %} +
+ {{ lang.t("Source code in") }} + {%- if function.relative_filepath.is_absolute() -%} + {{ function.relative_package_filepath }} + {%- else -%} + {{ function.relative_filepath }} + {%- endif -%} + + {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }} +
+ {% endif %} + {% endblock source %} + {% endblock contents %} +
-{% endblock heading %} + {% endwith %} +
diff --git a/docs/templates/python/material/module.html.jinja b/docs/templates/python/material/module.html.jinja index a61acfda9..1fb1cb695 100644 --- a/docs/templates/python/material/module.html.jinja +++ b/docs/templates/python/material/module.html.jinja @@ -1,12 +1,131 @@ -{% extends "_base/module.html.jinja" %} +{#- Template for Python modules. -{% block heading scoped %} - {% block source_link scoped %} - {% if config.extra.link_source and module.source_link %} - [source] +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 %} + +
+ {% 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 %} - {% endblock source_link %} - {{ super() }} + {% 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=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name), + skip_inventory=config.skip_local_inventory, + ) %} + + {% block heading scoped %} + {#- Heading block. + + This block renders the heading for the module. + -#} + {% block source_link scoped %} + {% if config.extra.link_source and module.source_link %} + [source] + {% endif %} + {% endblock source_link %} + + {% if config.show_symbol_type_heading %}{% endif %} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ module_name }} + {% else %} + {{ module_name }} + {% endif %} + {% endblock heading %} + + {% block labels scoped %} + {#- Labels block. + + This block renders the labels for the module. + -#} + {% with labels = module.labels %} + {% include "labels.html.jinja" with context %} + {% endwith %} + {% endblock labels %} + + {% endfilter %} + + {% else %} + {% if config.show_root_toc_entry %} + {% filter heading(heading_level, + role="module", + id=html_id, + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name), + hidden=True, + skip_inventory=config.skip_local_inventory, + ) %} + {% endfilter %} + {% endif %} + {% set heading_level = heading_level - 1 %} + {% 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.html.jinja" with context %} + {% endwith %} + {% endblock docstring %} + + {% block summary scoped %} + {#- Summary block. + + This block renders auto-summaries for classes, methods, and attributes. + -#} + {% include "summary.html.jinja" with context %} + {% endblock summary %} + + {% 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.html.jinja" with context %} + {% endblock children %} + {% endblock contents %} +
-{% endblock heading %} + {% endwith %} +
diff --git a/mkdocs.yml b/mkdocs.yml index 474307ba1..ac8f38eec 100644 --- a/mkdocs.yml +++ b/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/ @@ -327,13 +327,21 @@ extra_javascript: plugins: - search + - autorefs - minify: minify_html: true minify_css: true 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 +354,16 @@ 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 + backlinks: flat extra: link_source: true + extensions: + - hopsworks_apigen.mkdocs inventories: - https://docs.python.org/3/objects.inv - https://pandas.pydata.org/docs/objects.inv diff --git a/requirements-docs.txt b/requirements-docs.txt index e3e38fea1..40215a782 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -4,7 +4,9 @@ mike==2.1.3 markdown==3.9 pymdown-extensions==10.17.2 mkdocs-minify-plugin>=0.2.0 -mkdocs-multirepo-plugin==0.8.3 -mkdocstrings[python]==1.0.0 -mkdocstrings-python==2.0.1 +hopsworks-apigen@git+https://github.com/logicalclocks/hopsworks-apigen.git +mkdocstrings[python]==1.0.3 +mkdocstrings-python==2.0.2 +mkdocs-autorefs==1.4.4 +ruff==0.15.0 linkchecker