plesty.sdk.commands.docs
========================

.. py:module:: plesty.sdk.commands.docs

.. autoapi-nested-parse::

   CLI commands for previewing and deploying Sphinx documentation pages.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/plesty/sdk/commands/docs/deploy/index
   /reference/plesty/sdk/commands/docs/generate/index
   /reference/plesty/sdk/commands/docs/picker/index
   /reference/plesty/sdk/commands/docs/serve/index
   /reference/plesty/sdk/commands/docs/sphinx_builder/index


Attributes
----------

.. autoapisummary::

   plesty.sdk.commands.docs.pass_app_context


Classes
-------

.. autoapisummary::

   plesty.sdk.commands.docs.ApplicationContext


Functions
---------

.. autoapisummary::

   plesty.sdk.commands.docs.deploy_command
   plesty.sdk.commands.docs.serve_command
   plesty.sdk.commands.docs.docs_command


Package Contents
----------------

.. py:function:: deploy_command(context: plesty.sdk.context.ApplicationContext, remote_url: str, target_branch: str, release: bool) -> None

   Build and push the documentation pages for the Plesty project in the
   current working directory to the <TARGET_BRANCH> of the repository at
   <REMOTE_URL>. The branch is created if it does not yet exist.


.. py:function:: serve_command(context: plesty.sdk.context.ApplicationContext, dev_addr: str) -> None

   Start a local development webserver to preview the documentation pages
   for the Plesty project in the current working directory. Changes to the
   .md or .rst files are applied immediately via live reload.


.. py:class:: ApplicationContext(project_dir: pathlib.Path, quiet: bool = False)

   Container class for storing data shared across multiple commands.

   Initialize the application context with option values from the
   top-level 'plesty' command and populate property backing fields.

   :param project_dir: The path to the directory of the target Python
                       project, supplied via the --project-dir option.
   :param quiet: Suppress progress and guidance output, supplied via the
                 --quiet option.


   .. py:attribute:: project_directory
      :type:  pathlib.Path

      The path to the directory of the target Python project.


   .. py:attribute:: quiet
      :type:  bool

      Suppress progress and guidance output; failures and results still print.


   .. py:attribute:: _pyproject_toml
      :type:  dict[str, Any] | None


   .. py:attribute:: _docs_settings
      :type:  DocumentationSettings | None


   .. py:property:: pyproject_toml
      :type: dict[str, Any]


      The parsed content of the pyproject.toml file of the target Python project.


   .. py:property:: docs_settings
      :type: DocumentationSettings


      The documentation settings read from the pyproject.toml file.


   .. py:method:: ensure_docs_index() -> None

      Ensure that the docs directory exists and contains an index.md or index.rst
      file, as well as the external TOC file, if specified in the documentation settings.

      :raises click.ClickException: If a required file is missing.



.. py:data:: pass_app_context

   Decorator to pass the application context to a Click command as the first argument.

.. py:function:: docs_command(context: plesty.sdk.context.ApplicationContext) -> None

   Preview and deploy documentation pages.