hats.io.summary_file
====================

.. py:module:: hats.io.summary_file


Functions
---------

.. autoapisummary::

   hats.io.summary_file.write_skymap_png
   hats.io.summary_file.write_partition_info_png
   hats.io.summary_file.generate_summary
   hats.io.summary_file.write_catalog_summary_file


Module Contents
---------------

.. py:function:: write_skymap_png(catalog_path: str | pathlib.Path | upath.UPath) -> None

   
   Write a ``skymap.png`` pixel coverage map to the catalog directory.


   :Parameters:

       **catalog_path** : str | Path | UPath
           Path to the catalog directory. The PNG will be written alongside
           the catalog's other files.














   ..
       !! processed by numpydoc !!

.. py:function:: write_partition_info_png(catalog_path: str | pathlib.Path | upath.UPath) -> None

   
   Write a ``partition_info.png`` angular density map to the catalog directory.


   :Parameters:

       **catalog_path** : str | Path | UPath
           Path to the catalog directory. The PNG will be written alongside
           the catalog's other files.














   ..
       !! processed by numpydoc !!

.. py:function:: generate_summary(catalog, *, fmt: Literal['markdown', 'html'] | None = None, name: str, description: str, uri: str | None, huggingface_metadata: bool, jinja2_template: str | None = None, extra_template_vars: dict | None = None) -> str

   
   Generate summary content for any HATS catalog or collection.


   :Parameters:

       **catalog** : Catalog | CatalogCollection
           The HATS catalog or collection to summarize.

       **fmt** : Literal["markdown", "html"] | None
           Output format. Use ``"markdown"`` or ``"html"`` to render the built-in
           template, or ``None`` to supply a fully custom ``jinja2_template``.

       **name** : str
           Human-readable name rendered in the summary.

       **description** : str
           Description rendered in the summary.

       **uri** : str | None
           URI of the catalog used for hyperlinks and code-snippet examples.
           If ``None``, a placeholder is used.

       **huggingface_metadata** : bool
           Whether to include Hugging Face YAML frontmatter. Only valid when
           ``fmt="markdown"``.

       **jinja2_template** : str | None
           Jinja2 template string or path to a ``.jinja2`` file. If a file path
           is given, the file is read automatically. Overrides the built-in
           template when ``fmt`` is ``"markdown"`` or ``"html"``; required when
           ``fmt=None``.

       **extra_template_vars** : dict | None
           Additional variables passed into ``template.render()``. Useful for
           custom templates (e.g. VO registry XML fields) that reference variables
           HATS does not supply by default.



   :Returns:

       str
           Rendered summary content.











   ..
       !! processed by numpydoc !!

.. py:function:: write_catalog_summary_file(catalog_path: str | pathlib.Path | upath.UPath, *, fmt: Literal['markdown', 'html'] | None, filename: str | None = None, output_dir: str | pathlib.Path | upath.UPath | None = None, name: str | None = None, description: str | None = None, uri: str | None = None, huggingface_metadata: bool = False, jinja2_template: str | None = None, extra_template_vars: dict | None = None) -> upath.UPath

   
   Write a summary readme file for any HATS catalog or collection.


   :Parameters:

       **catalog_path** : str | Path | UPath
           Path to the HATS catalog or collection directory.

       **fmt** : Literal["markdown", "html"] | None
           Output format. Use ``"markdown"`` (writes ``README.md``) or ``"html"``
           (writes ``index.html``), or ``None`` to supply a fully custom
           ``jinja2_template`` and ``filename``.

       **filename** : str | None
           Output filename. Defaults to ``README.md`` for markdown and
           ``index.html`` for HTML. Required when ``fmt=None``.

       **output_dir** : str | Path | UPath | None
           Directory to write the file to. Defaults to ``catalog_path``.

       **name** : str | None
           Human-readable name. Inferred from catalog metadata if not provided.

       **description** : str | None
           Description. Inferred from catalog metadata if not provided.

       **uri** : str | None
           URI of the catalog used for hyperlinks and code-snippet examples.
           If ``None``, a placeholder is used.

       **huggingface_metadata** : bool
           Whether to include Hugging Face YAML frontmatter. Only valid when
           ``fmt="markdown"``.

       **jinja2_template** : str | None
           Jinja2 template string or path to a ``.jinja2`` file. If a file path
           is given, the file is read automatically. Overrides the built-in
           template when ``fmt`` is ``"markdown"`` or ``"html"``; required when
           ``fmt=None``.

       **extra_template_vars** : dict | None
           Additional variables passed into ``template.render()``. Useful for
           custom templates (e.g. VO registry XML fields) that reference variables
           HATS does not supply by default.



   :Returns:

       UPath
           Path to the written summary file.











   ..
       !! processed by numpydoc !!