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

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


Functions
---------

.. autoapisummary::

   hats.io.summary_file.write_collection_summary_file
   hats.io.summary_file.default_md_template
   hats.io.summary_file.generate_markdown_collection_summary


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

.. py:function:: write_collection_summary_file(collection_path: str | pathlib.Path | upath.UPath, *, fmt: Literal['markdown'], 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) -> upath.UPath

   
   Write a summary readme file for a HATS catalog.


   :Parameters:

       **collection_path: str | Path | UPath**
           The path to the HATS collection.

       **fmt** : str
           The format of the summary file. Currently only "markdown" is supported.

       **filename: str | None, default=None**
           The name of the summary file. If None, default depends on a `fmt`:
           - "README.md" for "markdown" format.

       **output_dir** : str | Path | UPath | None
           The root directory to output the summary file to. If None, the summary
           file would be written to the `collection_path`. If the directory does
           not exist, it would be created.

       **name** : str | None, default=None
           Human-readable name of the catalog. By default, generated based on
           catalog metadata.

       **description** : str | None, default=None
           Description of the catalog. By default, generated based on catalog
           metadata.

       **uri** : str | None, default=None
           URI of the catalog to use for the hyperlinks and code-snippet examples.
           Not validated. If None, a placeholder would be used for
           the code-snippets.

       **huggingface_metadata** : bool, default=False
           Whether to include Hugging Face specific metadata header in
           the Markdown file, by default False. Supported only when
           `fmt="markdown"`.

       **jinja2_template** : str, default=None
           `jinja2` template string to use for generating the summary file.
           If provided, it would override the default template from these
           functions:
           - `default_md_template()` for `fmt="markdown"`.



   :Returns:

       UPath
           The path to the written summary file.








   .. rubric:: Notes

   1. Not all options are supported for all formats.
   2. Default template is the subject of frequent changes, do not rely on it.



   ..
       !! processed by numpydoc !!

.. py:function:: default_md_template() -> str

   
   Get the default Jinja2 template string for generating Markdown summary files.





   :Returns:

       str
           The default Jinja2 template string.











   ..
       !! processed by numpydoc !!

.. py:function:: generate_markdown_collection_summary(collection: hats.catalog.catalog_collection.CatalogCollection, *, name: str, description: str, uri: str | None, huggingface_metadata: bool, jinja2_template: str | None = None) -> str

   
   Generate Markdown summary content for a HATS collection.


   :Parameters:

       **collection** : CatalogCollection
           HATS collection to generate summary for.

       **name** : str
           Title of the Markdown document.

       **description** : str
           Description of the catalog.

       **uri** : str | None
           URI of the catalog to use for the hyperlinks and code-snippet examples.
           Not validated. If None, a placeholder would be used for
           the code-snippets.

       **huggingface_metadata** : bool
           Whether to include Hugging Face specific metadata header in
           the Markdown file.

       **jinja2_template** : str | None
           ..














   ..
       !! processed by numpydoc !!