httk.core.docs.sitetree
=======================

.. py:module:: httk.core.docs.sitetree

.. autoapi-nested-parse::

   Compose immutable release and replaceable development documentation trees.



Exceptions
----------

.. autoapisummary::

   httk.core.docs.sitetree.ComposeError
   httk.core.docs.sitetree.ImmutabilityError


Classes
-------

.. autoapisummary::

   httk.core.docs.sitetree.ComposeResult


Functions
---------

.. autoapisummary::

   httk.core.docs.sitetree.compose_site


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

.. py:exception:: ComposeError

   Bases: :py:obj:`RuntimeError`


   Raised when a documentation tree contains unsafe or unsupported entries.


.. py:exception:: ImmutabilityError

   Bases: :py:obj:`RuntimeError`


   Raised when a rebuild differs from an already published release tree.


.. py:class:: ComposeResult

   Summarize one site composition operation.

   :param changed: Whether any generated site file changed.
   :param unchanged: Whether the requested target tree already matched.
   :param default_target: Manifest name selected as the site's default.
   :param versions: All published version labels, including development channels.


   .. py:attribute:: changed
      :type:  bool


   .. py:attribute:: unchanged
      :type:  bool


   .. py:attribute:: default_target
      :type:  str


   .. py:attribute:: versions
      :type:  tuple[str, ...]


.. py:function:: compose_site(site_root, build_html, *, slug, site_url, source_commit, target, repair = False)

   Compose a docs-site tree while preserving releases and maintaining latest.

   The root redirect lands on ``latest/`` when a release exists; ``latest/``
   is a replaceable duplicate of the newest release tree.

   ``repair=True`` is reserved for replacing an existing release after an
   approved manual repair. The replacement uses the same rename transaction
   as the development swap and never removes the live release in place.

   :param site_root: Root directory of the composed documentation site.
   :param build_html: Generated HTML tree to publish.
   :param slug: Site slug stored in the version manifest.
   :param site_url: Public site URL stored in the version manifest.
   :param source_commit: Source commit recorded in the version manifest.
   :param target: Release version or the replaceable development target.
   :param repair: Whether to replace an existing release after manual approval.
   :return: Summary of the composition result.
   :raises ComposeError: If the source, destination, or target is unsafe or invalid.
   :raises ImmutabilityError: If an existing release differs from the rebuilt tree.