docs: add doc tooling and layout from starbase

.github/workflows/docs.yaml

@@ -0,0 +1,38 @@
+name: docs
+on:
+  push:
+    branches:
+      - "main"
+      - "feature/*"
+      - "hotfix/*"
+      - "release/*"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yaml"
+
+jobs:
+  sphinx:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      - name: Install Tox
+        run: pip install tox
+      - name: Lint documentation
+        run: tox run -e lint-docs
+      - name: Build documentation
+        run: tox run -e build-docs
+      - name: Upload documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/_build/

.readthedocs.yml → .readthedocs.yaml

@@ -1,22 +1,27 @@
-# .readthedocs.yml
+# .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
+# Required
 version: 2
 
+# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
-build:
-  os: "ubuntu-20.04"
-  tools:
-    python: "3.8"
-
+# Optionally build your docs in additional formats such as PDF
 formats:
   - pdf
+  - epub
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
 
 python:
   install:
-    - requirements: docs/requirements.txt
     - method: pip
       path: .
+      extra_requirements:
+        - docs

HACKING.rst

@@ -0,0 +1,117 @@
+***************
+Craft Providers
+***************
+
+Welcome to Craft Providers! We hope this document helps you get started. Before
+contributing any code, please sign the `Canonical contributor licence
+agreement`_.
+
+Setting up a development environment
+------------------------------------
+We use a forking, feature-based workflow, so you should start by forking the
+repository. Once you've done that, clone the project to your computer using git
+clone's ``--recurse-submodules`` parameter. (See more on the `git submodules`_
+documentation.)
+
+Tooling
+=======
+We use a large number of tools for our project. Most of these are installed for
+you with tox, but you'll need to install:
+
+- Python 3.8 (default on Ubuntu 20.04, available on Ubuntu 22.04 through the
+  deadsnakes_ PPA) with setuptools.
+- tox_ version 4 or later. (3.8+ will automatically provision a v4 virtualenv)
+- Pyright_ (it's recommended you install with
+  ``snap install --classic pyright``)
+- ShellCheck_  (also available via snap: ``snap install shellcheck``)
+- pre-commit_
+
+Once you have all of those installed, you can install the necessary virtual
+environments for this repository using tox.
+
+Other tools
+###########
+Some other tools we use for code quality include:
+
+- Black_ for code formatting
+- pytest_ for testing
+- ruff_ for linting (and some additional formatting)
+
+A complete list is kept in our pyproject.toml_ file in dev dependencies.
+
+Initial Setup
+#############
+
+After cloning the repository but before making any changes, it's worth ensuring
+that the tests, linting and tools all run on your machine. Running ``tox`` with
+no parameters will create the necessary virtual environments for linting and
+testing and run those::
+
+    tox
+
+If you want to install the environments but not run the tests, you can run::
+
+    tox --notest
+
+If you'd like to run the tests with a newer version of Python, you can pass a
+specific environment. You must have an appropriately versioned Python
+interpreter installed. For example, to run with Python 3.10, run::
+
+    tox -e test-py310
+
+While the use of pre-commit_ is optional, it is highly encouraged, as it runs
+automatic fixes for files when ``git commit`` is called, including code
+formatting with ``black`` and ``ruff``.  The versions available in ``apt``
+from Debian 11 (bullseye), Ubuntu 22.04 (jammy) and newer are sufficient, but
+you can also install the latest with ``pip install pre-commit``. Once you've
+installed it, run ``pre-commit install`` in this git repository to install the
+pre-commit hooks.
+
+Tox environments and labels
+###########################
+
+We group tox environments with the following labels:
+
+* ``format``: Runs all code formatters with auto-fixing
+* ``type``: Runs all type checkers
+* ``lint``: Runs all linters (including type checkers)
+* ``unit-tests``: Runs unit tests in Python versions on supported LTS's + latest
+* ``integration-tests``: Same as above but for integration tests
+* ``tests``: The union of ``unit-tests`` and ``integration-tests``
+
+For each of these, you can see which environments will be run with
+``tox list``. For example:
+
+    tox list -m lint
+
+You can also see all the environments by simply running ``tox list``
+
+Running ``tox run -m format`` and ``tox run -m lint`` before committing code is
+recommended.
+
+
+Contributing code
+#################
+
+Please follow these guidelines when committing code for this project:
+
+* Use a topic with a colon to start the subject
+* Separate subject from body with a blank line
+* Limit the subject line to 50 characters
+* Do not capitalize the subject line
+* Do not end the subject line with a period
+* Use the imperative mood in the subject line
+* Wrap the body at 72 characters
+* Use the body to explain what and why (instead of how)
+
+.. _Black: https://black.readthedocs.io
+.. _`Canonical contributor licence agreement`: http://www.ubuntu.com/legal/contributors/
+.. _deadsnakes: https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa
+.. _`git submodules`: https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules
+.. _pre-commit: https://pre-commit.com/
+.. _pyproject.toml: ./pyproject.toml
+.. _Pyright: https://github.com/microsoft/pyright
+.. _pytest: https://pytest.org
+.. _ruff: https://github.com/charliermarsh/ruff
+.. _ShellCheck: https://www.shellcheck.net/
+.. _tox: https://tox.wiki

README.rst

@@ -0,0 +1,29 @@
+***************
+Craft providers
+***************
+
+Description
+-----------
+This project aims to provide Python interfaces for instantiating and executing
+builds for a variety of target environments.
+
+Initial providers include:
+- LXD containers
+- Multipass VMs
+
+Host support is targeted for:
+- Linux
+- Mac OS X
+- Windows
+
+License
+-------
+Free software: GNU Lesser General Public License v3
+
+ Documentation
+--------------
+https://canonical-craft-providers.readthedocs-hosted.com/en/latest/
+
+Contributing
+------------
+See the HACKING.rst document for details on how to contribute.

docs/_static/css/custom.css

@@ -0,0 +1,28 @@
+@import url('https://fonts.googleapis.com/css2?family=Ubuntu:ital@0;1&display=swap');
+
+body {
+    font-family: Ubuntu, "times new roman", times, roman, serif;
+}
+
+div .toctree-wrapper {
+    column-count: 2;
+}
+
+div .toctree-wrapper>ul {
+    margin: 0;
+}
+
+ul .toctree-l1 {
+    margin: 0;
+    -webkit-column-break-inside: avoid;
+    page-break-inside: avoid;
+    break-inside: avoid-column;
+}
+
+.wy-nav-content {
+    max-width: none;
+}
+
+.log-snippets {
+    color: rgb(141, 141, 141);
+}