Using Pyprefab
================

CLI
----

pyprefab is a command line interface (CLI) that requires only a few pieces of
information to create the boilerplate for a Python package.

To see the available options:

.. code-block:: bash

  pyprefab --help

.. typer:: pyprefab.cli.app
   :prog: pyprefab
   :theme: monokai

Example CLI use
################

To create a Python package named ``holodeck`` in a directory named
``trek/code/holodeck``:

.. code-block:: bash

  $ pyprefab --name holodeck --author rbarclay \
  --description "personal holodeck programs" \
  --dir trek/code/holodeck --docs

  ╭──────────── Package Created Successfully ─────────────╮
  │ ✨ Created new package holodeck in trek/code/holodeck │
  │ Author: rbarclay                                      │
  │ Description: personal holodeck programs               │
  │ Documentation: trek/code/holodeck/docs                │
  ╰───────────────────────────────────────────────────────╯

The scaffolding for the new ``holodeck`` package is now in the directory you
specified (in this case, ``trek/code/holodeck``).

.. code-block:: text

  trek/code/holodeck
    ├── .github
    │ ├── dependabot.yaml
    │ └── workflows
    │     ├── ci.yaml
    │     └── publish-pypi.yaml
    ├── .gitignore
    ├── .pre-commit-config.yaml
    ├── .python-version
    ├── CHANGELOG.md
    ├── CONTRIBUTING.md
    ├── docs
    │ └── source
    │     ├── _static
    │     │ └── custom.css
    │     ├── CHANGELOG.md
    │     ├── conf.py
    │     ├── CONTRIBUTING.md
    │     ├── index.rst
    │     ├── readme.md
    │     └── usage.md
    ├── LICENSE
    ├── pyproject.toml
    ├── README.md
    ├── src
    │ └── holodeck
    │     ├── __init__.py
    │     ├── __main__.py
    │     ├── app.py
    │     └── logging.py
    └── test
        └── test_app.py

Interactive mode
################

If you don't explicitly specify options, pyprefab will prompt for them:

.. code-block:: text

  $ pyprefab
  Package name 🐍: holodeck
  Package author 👤 [None]: rbarclay
  Package description 📝 [None]: personal holodeck programs
  Package directory 🎬 [/Users/rbarclay/code/holodeck]:
  Include Sphinx docs? 📄 [y/N]: y

  ╭───────────────── Package Created Successfully ──────────────╮
  │ Created new package holodeck in /Users/rbarclay/holode      │
  │ Author: rbarclay                                            │
  │ Description: personal holodeck programs                     │
  │ Documentation: /Users/rbarclay/holodeck/docs                │
  ╰─────────────────────────────────────────────────────────────╯

Using the new package
----------------------

Now you're ready to use the pyprefab-generated scaffolding to build your own
Python package.

Creating a dev environment for the new package
###############################################

Follow the steps below to create a development environment for Python packages
generated by pyprefab.

These directions use `uv`, but you can use your preferred tooling.

1. `cd` to the directory of the new Python package

2. Create a virtual environment and install the project dependencies:

  .. code-block:: bash

    $ uv sync

3. Test the project setupt:

  .. code-block:: bash

    $ uv run <your_package_name>

  You should see log output stating that the project has been set up correctly.

  For example:

  .. code-block:: text

    2025-01-13 02:29:08 [info] project_test successfully created.

  You can also run the tests:

  .. code-block:: bash

      $ uv run pytest


Previewing documentation
#########################

If your project includes the optional Sphinx documentation, make sure you can
build and preview the docs before updating them:

.. code-block:: bash

  $ uv run --group docs sphinx-autobuild docs/source docs/_build/html

The output of the above command provides a URL for viewing the documentation
via a local server (usually http://127.0.0.1:8000).

.. code-block:: text

  The HTML pages are in docs/_build/html.
  [sphinx-autobuild] Serving on http://127.0.0.1:8000
  [sphinx-autobuild] Waiting to detect changes...

Adding the project to git
##########################

To create a new git repository for the project (this is optional):

.. code-block:: bash

  $ git init
  $ git add .
  $ git commit -am "Initial commit"


.. tip::
  If you use `pre-commit <https://pre-commit.com/>`_, pyprefab's boilerplate
  includes a baseline ``pre-commit-config.yaml`` configuration. To use it, make
  sure the project has been added to git (see above) and install the pre-commit
  hooks: ``pre-commit install``


Hosting your project on GitHub
##############################

Code generated by pyprefab includes some extra boilerplate files for
projects hosted on GitHub. There are located in the ``.github`` directory, which
you can delete if you're not using GitHub.

GitHub workflows
+++++++++++++++++

The following
`GitHub workflow <https://docs.github.com/en/actions/writing-workflows/about-workflows>`_
files are generated by pyprefab. These are located in the ``.github/workflow``
directory:

- ``ci.yaml``: runs tests against multiple versions of python, checks test
  coverage, and runs a linter check using `ruff <https://astral.sh/ruff>`_
- ``publish-pypi.yaml``: publishes the package to
  `test PyPi <https://test.pypi.org>`_ and to `PyPI <https://pypi.org>`_
  (setup required, see comments in the file)

.. tip::
  GitHub reposistories have actions enabled by default, so review the workflow
  files to ensure that their
  `triggers <https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows>`_
  match your expectations.


Dependabot config
++++++++++++++++++

The ``.github`` directory also contains a configuration file for
`GitHub Dependabot <https://github.blog/news-insights/product-news/keep-all-your-packages-up-to-date-with-dependabot/>`_: ``dependabot.yaml``.

This file instructs Dependabot to check your project's
Python and GitHub action dependencies each week and submit pull requests if
there are any updates.

It's important to review and merge these pull requests regularly to keep your
code base secure.