Add acquire-zarr docs (#93)

* Add acquire-zarr docs

* Add Python and C API docs for acquire-zarr
* Add doxygen-generated files to gitignore
* Add Doxyfile for more configuration options
* Remove unwanted items from docs
* Remove individual attributes from Zarr Python API page
* Remove docstring rendering from module
* Update mkdocstrings options for new version

.github/workflows/deploy_docs.yml

@@ -53,6 +53,10 @@ jobs:
           cd acquire-docs
           mkdocs build
 
+      - name: Replace relative links in Doxygen include
+        run: |
+          sed -i 's@acquire_zarr_c_api/acquire_zarr_c_api#@#@g' site/stream_to_zarr/c_api/index.html
+
       - name: Deploy docs
         uses: peaceiris/actions-gh-pages@v3
         with:

.gitignore

@@ -1,2 +1,3 @@
 site/
 venv/
+docs/stream_to_zarr/acquire_zarr_c_api

README.md

@@ -16,9 +16,19 @@ We welcome contributions to the Acquire code base and to documentation. Refer to
 
 ## Build
 
-To build the website locally and serve it, run the following commands:
-
-```bash
-pip install -r requirements.txt
-mkdocs serve
-```
+To build the website locally and serve it, follow the steps below:
+
+1. Install `Doxygen` using your package manager or from the
+   [official website](https://www.doxygen.nl/index.html).
+2. after cloning and successfully installing `acquire-imaging` and
+   `acquire-zarr` in developer mode, run the following commands:
+
+    ```bash
+    pip install -r requirements.txt
+    mkdocs serve
+    ```
+
+> [!NOTE]
+> This setup assumes you have acquire-python and acquire-zarr cloned in the same
+> parent directory as acquire-docs. If this is not the case, edit the
+> [`mkdocs.yml` file](https://github.com/acquire-project/acquire-docs/blob/main/mkdocs.yml) accordingly.

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

@@ -36,7 +36,6 @@ Context:
         {% else %}
           {% set extra_level = 0 %}
         {% endif %}
-
         {# {% with attributes = obj.attributes|filter_objects(
             filters=config.filters,
             members_list=members_list,
@@ -70,7 +69,7 @@ Context:
             {% 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 %}
+                  {% include "class-no-attrs"|get_template with context %}
                 {% endif %}
               {% endfor %}
             {% endwith %}

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

@@ -0,0 +1,224 @@
+{#- Template for Python classes.
+
+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 %}
+
+<div class="doc doc-object doc-class">
+    {% 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 %}
+
+    {% 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=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|safe if
+    config.show_symbol_type_toc else '') + class.name,
+    ) %}
+
+    {% block heading scoped %}
+    {#- Heading block.
+
+    This block renders the heading for the class.
+    -#}
+    {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif
+    %}
+    {% if config.separate_signature %}
+    <span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
+    {% elif config.merge_init_into_class and "__init__" in all_members %}
+    {% with function = all_members["__init__"] %}
+    {%+ filter highlight(language="python", inline=True) %}
+    {{ class_name }}{% include "signature"|get_template with context %}
+    {% endfilter %}
+    {% endwith %}
+    {% else %}
+    <code>{{ class_name }}</code>
+    {% endif %}
+    {% endblock heading %}
+
+    {% block labels scoped %}
+    {#- Labels block.
+
+    This block renders the labels for the class.
+    -#}
+    {% with labels = class.labels %}
+    {% include "labels"|get_template 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 config.merge_init_into_class %}
+    {% if "__init__" in all_members %}
+    {% with function = all_members["__init__"] %}
+    {% if function.overloads %}
+    <div class="doc-overloads">
+        {% for overload in function.overloads %}
+        {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs)
+        %}
+        {{ class.name }}
+        {% endfilter %}
+        {% endfor %}
+    </div>
+    {% endif %}
+    {% if config.separate_signature %}
+    {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+    {{ class.name }}
+    {% endfilter %}
+    {% endif %}
+    {% endwith %}
+    {% endif %}
+    {% endif %}
+    {% endblock signature %}
+
+    {% else %}
+    {% if config.show_root_toc_entry %}
+    {% filter heading(heading_level,
+    role="class",
+    id=html_id,
+    toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|safe if
+    config.show_symbol_type_toc else '') + class.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 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 %}
+        <p class="doc doc-class-bases">
+            Bases: {% for expression in class.bases -%}
+            <code>{% include "expression"|get_template with context %}</code>{% if not loop.last %}, {% endif %}
+            {% endfor -%}
+        </p>
+        {% endif %}
+        {% endblock bases %}
+
+        {% block docstring scoped %}
+        {#- Docstring block.
+
+        This block renders the docstring for the class.
+        -#}
+        {% with docstring_sections = class.docstring.parsed %}
+        {% include "docstring"|get_template 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"|get_template with context %}
+        {% endwith %}
+        {% endwith %}
+        {% endif %}
+        {% endwith %}
+        {% endif %}
+        {% endblock docstring %}
+
+        {% block summary scoped %}
+        {#- Summary block.
+
+        This block renders auto-summaries for classes, methods, and attributes.
+        -#}
+        {% include "summary"|get_template 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__"] %}
+        <details class="quote">
+            <summary>Source code in <code>
+                      {%- if init.relative_filepath.is_absolute() -%}
+                        {{ init.relative_package_filepath }}
+                      {%- else -%}
+                        {{ init.relative_filepath }}
+                      {%- endif -%}
+                    </code></summary>
+            {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+        </details>
+        {% endwith %}
+        {% endif %}
+        {% elif class.source %}
+        <details class="quote">
+            <summary>Source code in <code>
+                  {%- if class.relative_filepath.is_absolute() -%}
+                    {{ class.relative_package_filepath }}
+                  {%- else -%}
+                    {{ class.relative_filepath }}
+                  {%- endif -%}
+                </code></summary>
+            {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+        </details>
+        {% 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-no-attrs"|get_template with context %}
+        {% endblock children %}
+        {% endblock contents %}
+    </div>
+
+    {% endwith %}
+</div>

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

@@ -87,16 +87,6 @@ Context:
         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.
           

docs/stream_to_zarr/Doxyfile

@@ -0,0 +1,69 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "acquire_zarr_c_api"
+OUTPUT_DIRECTORY       = acquire_zarr_c_api
+CREATE_SUBDIRS         = NO
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+SHORT_NAMES            = NO
+PYTHON_DOCSTRING       = YES
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 6
+MARKDOWN_ID_STYLE      = DOXYGEN
+AUTOLINK_SUPPORT       = YES
+TYPEDEF_HIDES_STRUCT   = YES
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+RESOLVE_UNNAMED_PARAMS = YES
+HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_CLASSES     = YES
+HIDE_UNDOC_NAMESPACES  = YES
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE = YES
+SHOW_HEADERFILE        = NO
+SHOW_INCLUDE_FILES     = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SHOW_USED_FILES        = NO
+SHOW_FILES             = NO
+SHOW_NAMESPACES        = YES
+QUIET                  = NO
+WARNINGS               = YES
+WARN_AS_ERROR          = NO
+INPUT                  = "../../acquire-zarr/include"
+FILE_PATTERNS          = *.h
+RECURSIVE              = NO
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_SYMBOLS        = ZarrCompressionCodec, ZarrCompressor, ZarrDataType, ZarrDimensionType, ZarrLogLevel, ZarrStatusCode, ZarrVersion 
+FILTER_SOURCE_FILES    = NO
+IMPLICIT_DIR_DOCS      = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_CODE_FOLDING      = YES
+HTML_COPY_CLIPBOARD    = YES
+HTML_INDEX_NUM_ENTRIES = 100
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = YES
+FULL_SIDEBAR           = NO
+SHOW_ENUM_VALUES       = NO
+TREEVIEW_WIDTH         = 250
+USE_MATHJAX            = NO
+SEARCHENGINE           = YES
+GENERATE_XML           = YES

docs/stream_to_zarr/c_api.md

@@ -0,0 +1,19 @@
+# Zarr Streaming C API Reference
+
+Information on the `acquire_zarr` C implementation and how to use it. Check
+https://github.com/acquire-project/acquire-zarr for more information.
+
+## `acquire.zarr.h`
+
+{% include-markdown
+    "./acquire_zarr_c_api/acquire_zarr_c_api/acquire_8zarr_8h.md"
+    start="(acquire_8zarr_8h.md)"
+%}
+
+## `zarr.types.h`
+
+{%
+    include-markdown
+    "./acquire_zarr_c_api/acquire_zarr_c_api/zarr_8types_8h.md"
+    start="(zarr_8types_8h.md)"
+%}