From df6c688f2b7591495e1644d1ef5e312fe50091ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 6 Feb 2025 16:51:17 -0300 Subject: [PATCH] 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 | 4 + .gitignore | 1 + README.md | 22 +- .../material/children-no-attrs.html.jinja | 3 +- .../python/material/class-no-attrs.html.jinja | 224 ++++++++++++++++++ .../python/material/module.html.jinja | 10 - docs/stream_to_zarr/Doxyfile | 69 ++++++ docs/stream_to_zarr/c_api.md | 19 ++ docs/stream_to_zarr/index.md | 28 +++ docs/stream_to_zarr/zarr_api.md | 6 + mkdocs.yml | 26 +- overrides/home_zarr.html | 95 ++++++++ requirements.txt | 2 + 13 files changed, 486 insertions(+), 23 deletions(-) create mode 100644 docs/_templates/python/material/class-no-attrs.html.jinja create mode 100644 docs/stream_to_zarr/Doxyfile create mode 100644 docs/stream_to_zarr/c_api.md create mode 100644 docs/stream_to_zarr/index.md create mode 100644 docs/stream_to_zarr/zarr_api.md create mode 100644 overrides/home_zarr.html diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index 974fbe9a..eb5002f0 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.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: diff --git a/.gitignore b/.gitignore index 9edfe639..14f94ae8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ site/ venv/ +docs/stream_to_zarr/acquire_zarr_c_api diff --git a/README.md b/README.md index 3a22d6a6..54c6cf3b 100644 --- a/README.md +++ b/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. diff --git a/docs/_templates/python/material/children-no-attrs.html.jinja b/docs/_templates/python/material/children-no-attrs.html.jinja index 003e459d..ffac5833 100644 --- a/docs/_templates/python/material/children-no-attrs.html.jinja +++ b/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 %} diff --git a/docs/_templates/python/material/class-no-attrs.html.jinja b/docs/_templates/python/material/class-no-attrs.html.jinja new file mode 100644 index 00000000..18fc6ff7 --- /dev/null +++ b/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 %} + +
+ {% 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=(' '|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 %}{% endif + %} + {% if 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 }}{% include "signature"|get_template with context %} + {% endfilter %} + {% endwith %} + {% else %} + {{ class_name }} + {% 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 %} +
+ {% 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 %} + {% 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=(' '|safe if + config.show_symbol_type_toc else '') + class.name, + hidden=True, + ) %} + {% 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 -%} + {% include "expression"|get_template with context %}{% if not loop.last %}, {% endif %} + {% endfor -%} +

+ {% 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__"] %} +
+ 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 %} +
+ 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-no-attrs"|get_template with context %} + {% endblock children %} + {% endblock contents %} +
+ + {% endwith %} +
\ No newline at end of file diff --git a/docs/_templates/python/material/module.html.jinja b/docs/_templates/python/material/module.html.jinja index d93dd5a8..8e75651a 100644 --- a/docs/_templates/python/material/module.html.jinja +++ b/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. diff --git a/docs/stream_to_zarr/Doxyfile b/docs/stream_to_zarr/Doxyfile new file mode 100644 index 00000000..1a55798c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/stream_to_zarr/c_api.md b/docs/stream_to_zarr/c_api.md new file mode 100644 index 00000000..55e4fa7e --- /dev/null +++ b/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)" +%} diff --git a/docs/stream_to_zarr/index.md b/docs/stream_to_zarr/index.md new file mode 100644 index 00000000..87dfb200 --- /dev/null +++ b/docs/stream_to_zarr/index.md @@ -0,0 +1,28 @@ +--- +title: Stream to Zarr +template: home_zarr.html +--- + +
+
+

Python API Reference

+

Information on classes and methods

+ Python API Reference +
+
+

C API Reference

+

Information on classes and methods

+ C API Reference +
+
+

Python Examples

+

Examples that demonstrate how to use the python library

+ Python Examples +
+
+

C Examples

+

Examples that demonstrate how to use the C library

+ C Examples +
+
+ diff --git a/docs/stream_to_zarr/zarr_api.md b/docs/stream_to_zarr/zarr_api.md new file mode 100644 index 00000000..0620a51c --- /dev/null +++ b/docs/stream_to_zarr/zarr_api.md @@ -0,0 +1,6 @@ +# Zarr Streaming Python API Reference + +Information on classes and methods for the `acquire_zarr` Python library. Check +https://github.com/acquire-project/acquire-zarr for more information. + +::: acquire_zarr diff --git a/mkdocs.yml b/mkdocs.yml index af593a83..122a9bb1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,10 @@ nav: - for_contributors/index.md - for_contributors/docs_contribution_quickstart.md - for_contributors/update_version.md + - Stream to Zarr: + - stream_to_zarr/index.md + - stream_to_zarr/zarr_api.md + - stream_to_zarr/c_api.md markdown_extensions: - pymdownx.highlight: @@ -85,20 +89,23 @@ markdown_extensions: plugins: - - include-markdown + - include-markdown: + heading_offset: 1 + rewrite_relative_urls: true - search + - awesome-pages - mkdocstrings: custom_templates: docs/_templates + enable_inventory: true # Create an objects.inv file handlers: python: # Global-only options load_external_modules: true - paths: [../acquire-python/python/acquire] - import: + paths: [../acquire-python/python/acquire, ../acquire-zarr/python/acquire_zarr] + inventories: - https://docs.python.org/3/objects.inv options: # See https://mkdocstrings.github.io/python/usage/#globallocal-options # General options - enable_inventory: true # Create an objects.inv file show_source: false # Do now show source code for objects # Heading options show_root_heading: false # Do now show module name as heading, default @@ -109,9 +116,9 @@ plugins: # Members options members: true # An explicit list of members to render (true for all) inherited_members: false # Do not render any inherited members (for classes) + summary: true members_order: "alphabetical" # Order members alphabetically, default filters: ["!^_", "!dict", "!setup_", "!gui"] # Remove private and unwanted members - summary: true # Whether to render summaries of objects. Insiders only for now show_labels: false # Whether to show labels of the members # Docstring options docstring_style: google @@ -122,3 +129,12 @@ plugins: annotations_path: "brief" # The verbosity for annotations path, default show_signature_annotations: true # Show the type annotations in methods and functions signatures signature_crossrefs: true # Whether to render cross-references for type annotations in signatures + - mkdoxy: + projects: + acquire_zarr_c_api: # name of project must be alphanumeric + numbers (without spaces) + src-dirs: ../acquire-zarr/include # path to source code (support multiple paths separated by space) => INPUT + full-doc: True # if you want to generate full documentation + doxy-cfg-file: docs/stream_to_zarr/Doxyfile + save-api: docs/stream_to_zarr + +use_directory_urls: true diff --git a/overrides/home_zarr.html b/overrides/home_zarr.html new file mode 100644 index 00000000..93ac25f4 --- /dev/null +++ b/overrides/home_zarr.html @@ -0,0 +1,95 @@ + + +{% extends "main.html" %} + +{% block header %} +{% include "./partials/header.html" %} +{% endblock %} + + +{% block tabs %} +{{ super() }} + + + + + +
+
+
+ +
+

Stream to Zarr

+

The Acquire Zarr Streaming library supports chunked, compressed, multiscale streaming to + Zarr, with + OME-NGFF metadata.

+ + Get Started + +
+
+
+
+{% endblock %} + + +{% block content %} + {{ super() }} + +{% endblock %} + + +{% block footer %} +{% include "./partials/footer.html" %} +{% endblock %} diff --git a/requirements.txt b/requirements.txt index ebf0e4e0..42d32a5e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,3 +5,5 @@ griffe jupytext pre-commit mike +mkdoxy +mkdocs-awesome-pages-plugin