From 61a679349aac3d0e8db214e736d65d3c63265868 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Thu, 8 Jun 2023 13:53:54 -0500 Subject: [PATCH 1/3] docs: add doc tooling and layout from starbase Signed-off-by: Callahan Kovacs --- .github/workflows/docs.yaml | 38 +++++++++ .readthedocs.yml => .readthedocs.yaml | 19 +++-- docs/Makefile | 20 ----- docs/_static/.gitempty | 0 docs/_static/css/custom.css | 28 +++++++ docs/changelog.rst | 65 ++++++++------- docs/conf.py | 110 ++++++++------------------ docs/explanation/index.rst | 25 ++++++ docs/explanations.rst | 12 --- docs/howto/index.rst | 7 ++ docs/index.rst | 49 +++++++++--- docs/{ => reference}/bases.rst | 0 docs/{ => reference}/executors.rst | 0 docs/reference/index.rst | 10 +++ docs/requirements.txt | 10 --- docs/tutorials/index.rst | 11 +++ pyproject.toml | 12 ++- tox.ini | 51 ++++++------ 18 files changed, 271 insertions(+), 196 deletions(-) create mode 100644 .github/workflows/docs.yaml rename .readthedocs.yml => .readthedocs.yaml (51%) delete mode 100644 docs/Makefile delete mode 100644 docs/_static/.gitempty create mode 100644 docs/_static/css/custom.css create mode 100644 docs/explanation/index.rst delete mode 100644 docs/explanations.rst create mode 100644 docs/howto/index.rst rename docs/{ => reference}/bases.rst (100%) rename docs/{ => reference}/executors.rst (100%) create mode 100644 docs/reference/index.rst delete mode 100644 docs/requirements.txt create mode 100644 docs/tutorials/index.rst diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..2e06b6c3 --- /dev/null +++ b/.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/ diff --git a/.readthedocs.yml b/.readthedocs.yaml similarity index 51% rename from .readthedocs.yml rename to .readthedocs.yaml index efed0d77..fb581170 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d4bb2cbb..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/.gitempty b/docs/_static/.gitempty deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..ef7e97f6 --- /dev/null +++ b/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); +} diff --git a/docs/changelog.rst b/docs/changelog.rst index 38dc3d76..0126a93c 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -16,17 +16,18 @@ Changelog - Add AlmaLinux 9 base - Add stricter typing for base names - Refactor CI workflow -- Refactor Multipass `push_file_io` +- Refactor Multipass ``push_file_io`` - Pin dependency urllib3<2 1.11.0 (2023-04-19) ------------------- -- Move Snap pydantic model from `bases.buildd` to `actions.snap_installer` -- Rename `bases.buildd` module to `bases.ubuntu` -- Determine base alias from base configuration in `provider.launched_environment()` -- Add new functions `get_base_alias()` and `get_base_from_alias()` +- Move Snap pydantic model from ``bases.buildd`` to ``actions.snap_installer`` +- Rename ``bases.buildd`` module to ``bases.ubuntu`` +- Determine base alias from base configuration in + ``provider.launched_environment()`` +- Add new functions ``get_base_alias()`` and ``get_base_from_alias()`` - Add CentOS 7 base -- Add default for `launched_environment()` parameter `allow_unstable=False` +- Add default for ``launched_environment()`` parameter ``allow_unstable=False`` - Trim suffixes from snap names when installing snaps. 1.10.0 (2023-03-31) @@ -39,41 +40,44 @@ Changelog ------------------ - Set cloud.cfg to not reset apt's source list for buildd bases - Store LXD instance's full name in the config's description -- Add `allow_unstable` parameter to `Provider.launched_environment()` +- Add ``allow_unstable`` parameter to ``Provider.launched_environment()`` 1.8.1 (2023-03-10) ------------------ -- Add new base alias `BuilddBaseAlias.DEVEL` +- Add new base alias ``BuilddBaseAlias.DEVEL`` - Expire unstable base instances every 14 days - Refactor tests such that all base aliases are tested by default 1.8.0 (2023-03-01) ------------------ -- Track if instances are properly setup when launching. If the instance did not fully - complete setup and auto-clean is enabled, the instance will be cleaned and recreated. -- Add new field `setup` to instance configuration to track set up status -- Update base compatibility tag from `base-v0` to `base-v1` +- Track if instances are properly setup when launching. If the instance did not + fully complete setup and auto-clean is enabled, the instance will be cleaned + and recreated. +- Add new field ``setup`` to instance configuration to track set up status +- Update base compatibility tag from ``base-v0`` to ``base-v1`` - Add new BuilddBaseAliases for Lunar and Kinetic - Add support for interim Ubuntu releases for LXD - Add support for custom LXD image remotes. LXD remotes can now add any - remote server to retrieve images from using the `RemoteImage` class. -- Add deprecation warning for LXD function `configure_buildd_image_remote()`. - Usage of this function should be replaced with RemoteImage's `add_remote()`. -- Rename BuilddBase function `setup_instance_config()` to `update_compatibility_tag()` + remote server to retrieve images from using the ``RemoteImage`` class. +- Add deprecation warning for LXD function ``configure_buildd_image_remote()``. + Usage of this function should be replaced with RemoteImage's ``add_remote()``. +- Rename BuilddBase function ``setup_instance_config()`` to + ``update_compatibility_tag()`` - Update brew for macos CI tests - Update readthedocs link in readme - Capture subproccess error details when snap removal fails -- Add default for `_run_lxc()` parameter `check=True` +- Add default for ``_run_lxc()`` parameter ``check=True`` - Refactor lxd unit and integration tests - Enable more pylint checks -- Use new `use_base_instance` parameter when launching LXD instances from LXDProvider +- Use new ``use_base_instance`` parameter when launching LXD instances from + LXDProvider 1.7.2 (2023-02-06) ------------------ - Check LXD id map before starting an existing instance. If the id map does not match, the instance will be auto cleaned or an error will be raised. -- Add `lxc.config_get()` method to retrieve config values +- Add ``lxc.config_get()`` method to retrieve config values 1.7.1 (2023-01-23) ------------------ @@ -84,15 +88,15 @@ Changelog ------------------ - LXD instances launch from a cached base instance rather than a base image. This reduces disk usage and launch time. -- For the LXD launch function `launched_environment`, the parameter `use_snapshots` - has been replaced by `use_base_instance`. `use_snapshots` still works but logs - a deprecation notice. +- For the LXD launch function ``launched_environment``, the parameter + ``use_snapshots`` has been replaced by ``use_base_instance``. + ``use_snapshots`` still works but logs a deprecation notice. - Expire and recreate base instances older than 3 months (90 days) -- Add `lxc.copy()` method to copy instances +- Add ``lxc.copy()`` method to copy instances - Check for network connectivity after network-related commands fail - Add documentation for network connectivity issues inside instances - Enable testing for Ubuntu 22.04 images -- Update `MultipassInstance.push_file_io()` to work regardless of the +- Update ``MultipassInstance.push_file_io()`` to work regardless of the host's working directory 1.6.2 (2022-12-08) @@ -111,10 +115,11 @@ Changelog Note: The new Provider classes are used to encapsulate LXD and Multipass, from installing the provider to creating and managing instances. The code - was leveraged from the craft applications (snapcraft, charmcraft, rockcraft, - lpcraft), which implemented similar variations of these Provider classes. - These classes are not stable and are likely to change. They will be stable and - recommended for use in the release of craft-providers 2.0. + was leveraged from the craft applications (snapcraft, charmcraft, + rockcraft, lpcraft), which implemented similar variations of these + Provider classes. These classes are not stable and are likely to change. + They will be stable and recommended for use in the release of + craft-providers 2.0. 1.5.1 (2022-09-29) ------------------ @@ -124,7 +129,9 @@ Note: The new Provider classes are used to encapsulate LXD and Multipass, 1.5.0 (2022-09-23) ------------------ - Add mount method to Executor base class -- LXDInstance's mount method signature has changed - The optional parameter `device_name` has been deprecated. It now matches MultipassInstance's signature of `mount(host_source, target)` +- LXDInstance's mount method signature has changed - The optional parameter + ``device_name`` has been deprecated. It now matches MultipassInstance's + signature of ``mount(host_source, target)`` - Signed snaps injected into a provider are asserted - Existing .snap files are not removed before overwriting with a new .snap file diff --git a/docs/conf.py b/docs/conf.py index 9d2f3ef7..28971c92 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,102 +1,62 @@ -# -# Copyright 2021-2023 Canonical Ltd. -# -# This program is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License version 3 as published by the Free Software Foundation. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public License -# along with this program; if not, write to the Free Software Foundation, -# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - # Configuration file for the Sphinx documentation builder. # -# This file only contains a selection of the most common options. For a full -# list see the documentation: +# For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -sys.path.insert(0, os.path.abspath("..")) - - # -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "Craft Providers" -copyright = "2021-2023, Canonical Ltd." -author = "Canonical Ltd." +copyright = "2021-2023, Canonical" +author = "Canonical" +# region General configuration +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", # must be loaded after napoleon + "sphinx.ext.coverage", + "sphinx.ext.doctest", + "sphinx_design", + "sphinx_copybutton", "sphinx-pydantic", + "sphinx_toolbox", + "sphinx_toolbox.more_autodoc", + "sphinx.ext.autodoc", # Must be loaded after more_autodoc ] -# Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +show_authors = False -# -- Options for HTML output ------------------------------------------------- +# endregion +# region Options for HTML output +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". +html_theme = "furo" html_static_path = ["_static"] +html_css_files = [ + "css/custom.css", +] -# Do (not) include module names. -add_module_names = True +# endregion +# region Options for extensions +# Intersphinx extension +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration -# sphinx_autodoc_typehints +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} + +# Type hints configuration set_type_checking_flag = True typehints_fully_qualified = False always_document_param_types = True -typehints_document_rtype = True - -# Enable support for google-style instance attributes. -napoleon_use_ivar = True - - -def run_apidoc(_): - from sphinx.ext.apidoc import main # type: ignore - import os - import sys - - sys.path.append(os.path.join(os.path.dirname(__file__), "..")) - cur_dir = os.path.abspath(os.path.dirname(__file__)) - module = os.path.join(cur_dir, "..", "craft_providers") - main(["-e", "-o", cur_dir, module, "--no-toc", "--force"]) +# Github config +github_username = "canonical" +github_repository = "craft-providers" -def setup(app): - app.connect("builder-inited", run_apidoc) +# endregion diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst new file mode 100644 index 00000000..d41e748a --- /dev/null +++ b/docs/explanation/index.rst @@ -0,0 +1,25 @@ +.. _explanation: + +Explanation +*********** + +.. toctree:: + :maxdepth: 1 + +Failure to properly execute commands that depend on network access +================================================================== + +A common problem that can occur when running the setup or warmup of an instance +is a failure associated with different processes (e.g. ``apt``) not being able +to access the network properly. + +While this can happen because of a myriad of situations (network outage in the +host, a malfunctioning proxy, etc), there is a very common case where Docker +changes the ``iptables`` of the host in a particular way that conflicts with LXD +instances. + +If you're getting network errors in an LXD instance and have Docker installed, +please refer to `this section`_ in the Linux Containers documentation for more +information and ways to solve the situation. + +.. _`this section`: https://linuxcontainers.org/lxd/docs/master/howto/network_bridge_firewalld/#prevent-connectivity-issues-with-lxd-and-docker diff --git a/docs/explanations.rst b/docs/explanations.rst deleted file mode 100644 index efe67485..00000000 --- a/docs/explanations.rst +++ /dev/null @@ -1,12 +0,0 @@ -************ -Explanations -************ - -Failure to properly execute commands that depend on network access -================================================================== - -A common problem that can occur when running the setup or warmup of an instance is a failure associated with different processes (e.g. ``apt``) not being able to access the network properly. - -While this can happen because of a myriad of situations (network outage in the host, a malfunctioning proxy, etc), there is a very common case where Docker changes the `iptables` of the host in a particular way that conflicts with LXD instances. - -If you're getting network errors in an LXD instance and have Docker installed, please refer to `this section in the Linux Containers documentation `_ for more information and ways to solve the situation. diff --git a/docs/howto/index.rst b/docs/howto/index.rst new file mode 100644 index 00000000..436a1880 --- /dev/null +++ b/docs/howto/index.rst @@ -0,0 +1,7 @@ +.. _howto: + +How-to guides +************* + +.. toctree:: + :maxdepth: 1 diff --git a/docs/index.rst b/docs/index.rst index b2aad777..5085c154 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,6 @@ -Welcome to Craft Providers' documentation! +.. craft providers documentation root file + +Craft Providers =========================================== Craft Providers is a Python package for managing software builds in containers @@ -16,25 +18,46 @@ This package is most useful for implementers of tools using the Craft Parts framework that need to provide support for additional build environments. .. toctree:: - :caption: Public APIs: + :maxdepth: 1 + :hidden: - executors + tutorials/index + howto/index + reference/index + explanation/index + changelog - bases +.. grid:: 1 1 2 2 -.. toctree:: - :caption: Internal APIs: + .. grid-item-card:: :ref:`Tutorial ` -.. toctree:: - :caption: Reference: + **Get started** with a hands-on introduction to Craft Providers + + .. grid-item-card:: :ref:`How-to guides ` + + **Step-by-step guides** covering key operations and common tasks + +.. grid:: 1 1 2 2 + :reverse: + + .. grid-item-card:: :ref:`Reference ` + + **Technical information** about Craft Providers + + .. grid-item-card:: :ref:`Explanation ` + + **Discussion and clarification** of key topics - craft_providers +Project and community +===================== -.. toctree:: - :caption: Explanations: - - explanations +Craft Providers is a member of the Canonical family. It's an open source project +that warmly welcomes community projects, contributions, suggestions, fixes +and constructive feedback. +* `Ubuntu Code of Conduct `_. +* `Canonical contributor licenses agreement + `_. Indices and tables ================== diff --git a/docs/bases.rst b/docs/reference/bases.rst similarity index 100% rename from docs/bases.rst rename to docs/reference/bases.rst diff --git a/docs/executors.rst b/docs/reference/executors.rst similarity index 100% rename from docs/executors.rst rename to docs/reference/executors.rst diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 00000000..32f7dccb --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,10 @@ +.. _reference: + +Reference +********* + +.. toctree:: + :maxdepth: 1 + + bases + executors diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index e1ce92ce..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,10 +0,0 @@ -Sphinx==4.2.0 -sphinx-autodoc-typehints==1.12.0 -sphinx-jsonschema==1.16.11 -sphinx-pydantic==0.1.1 -sphinx-rtd-theme==1.0.0 -sphinxcontrib-applehelp==1.0.2 -sphinxcontrib-devhelp==1.0.2 -sphinxcontrib-htmlhelp==2.0.0 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.3 diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 00000000..eeb0a5cd --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,11 @@ +.. _tutorial: + +Tutorials +********* + +If you want to learn the basics from experience, then our tutorials will help +you acquire the necessary competencies from real-life examples with fully +reproducible steps. + +.. toctree:: + :maxdepth: 1 diff --git a/pyproject.toml b/pyproject.toml index ef6f972a..8bc8ce24 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,10 +53,14 @@ types = [ "pyright==1.1.311", ] docs = [ - "sphinx", - "sphinx-autodoc-typehints", - "sphinx-pydantic", - "sphinx-rtd-theme", + "furo==2023.5.20", + "sphinx>=6.2.1,<7.0", + "sphinx-autobuild==2021.3.14", + "sphinx-copybutton==0.5.2", + "sphinx-design==0.4.1", + "sphinx-pydantic==0.1.1", + "sphinx-toolbox==3.4.0", + "sphinx-lint==0.6.7", ] [build-system] diff --git a/tox.ini b/tox.ini index 386b1ed7..e5500e41 100644 --- a/tox.ini +++ b/tox.ini @@ -95,29 +95,28 @@ commands = ruff: ruff --fix --respect-gitignore {posargs} . codespell: codespell --toml {tox_root}/pyproject.toml --write-changes {posargs} -# docs are not yet configured (see #287 or CRAFT-1799) -# [docs] # Sphinx documentation configuration -# extras = docs -# package = editable -# no_package = true -# env_dir = {work_dir}/docs -# runner = ignore_env_name_mismatch -# -# [testenv:build-docs] -# description = Build sphinx documentation -# base = docs -# allowlist_externals = bash -# commands_pre = bash -c 'if [[ ! -e docs ]];then echo "No docs directory. Run `tox run -e sphinx-quickstart` to create one.;";return 1;fi' -# # "-W" is to treat warnings as errors -# commands = sphinx-build {posargs:-b html} -W {tox_root}/docs {tox_root}/docs/_build -# -# [testenv:autobuild-docs] -# description = Build documentation with an autoupdating server -# base = docs -# commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --watch {tox_root}/starcraft {tox_root}/docs {tox_root}/docs/_build -# -# [testenv:lint-docs] -# description = Lint the documentation with sphinx-lint -# base = docs -# commands = sphinx-lint --ignore docs/_build --max-line-length 80 -e all {posargs} docs/ -# labels = lint +[docs] # Sphinx documentation configuration +extras = docs +package = editable +no_package = true +env_dir = {work_dir}/docs +runner = ignore_env_name_mismatch + +[testenv:build-docs] +description = Build sphinx documentation +base = docs +allowlist_externals = bash +commands_pre = bash -c 'if [[ ! -e docs ]];then echo "No docs directory. Run `tox run -e sphinx-quickstart` to create one.;";return 1;fi' +# "-W" is to treat warnings as errors +commands = sphinx-build {posargs:-b html} -W {tox_root}/docs {tox_root}/docs/_build + +[testenv:autobuild-docs] +description = Build documentation with an autoupdating server +base = docs +commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --watch {tox_root}/craft_providers {tox_root}/docs {tox_root}/docs/_build + +[testenv:lint-docs] +description = Lint the documentation with sphinx-lint +base = docs +commands = sphinx-lint --ignore docs/_build --max-line-length 80 -e all {posargs} docs/ +labels = lint From c3e99cc24a919476d7063b8032a2cece80c0403f Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Thu, 8 Jun 2023 14:14:47 -0500 Subject: [PATCH 2/3] docs: reformat README, add HACKING Signed-off-by: Callahan Kovacs --- HACKING.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 73 ---------------------------------------- README.rst | 29 ++++++++++++++++ 3 files changed, 124 insertions(+), 73 deletions(-) create mode 100644 HACKING.rst delete mode 100644 README.md create mode 100644 README.rst diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 00000000..af0f36c6 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,95 @@ +********* +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 diff --git a/README.md b/README.md deleted file mode 100644 index 801f1bf7..00000000 --- a/README.md +++ /dev/null @@ -1,73 +0,0 @@ -# Craft Providers - -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 - -A `Makefile` is provided for easy interaction with the project. To see -all available options run: - -``` -make help -``` - -## Running tests - -To run all tests in the suite run: - -``` -make tests -``` - -## Adding new requirements - -If a new dependency is added to the project run: - -``` -make freeze-requirements -``` - -## Verifying documentation changes - -To locally verify documentation changes run: - -``` -make docs -``` - -After running, newly generated documentation shall be available at -`./docs/_build/html/`. - - -## Committing 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) diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..ce7bdd65 --- /dev/null +++ b/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. From c097d03e349f988d450e829b130661c5e1e09491 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Fri, 16 Jun 2023 09:20:44 -0500 Subject: [PATCH 3/3] feedback from PR Signed-off-by: Callahan Kovacs --- HACKING.rst | 48 +++++++++++++++++++++++++++++++++++------------- tox.ini | 2 +- 2 files changed, 36 insertions(+), 14 deletions(-) diff --git a/HACKING.rst b/HACKING.rst index af0f36c6..6a0f896a 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -1,24 +1,33 @@ -********* +*************** 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`_. +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.) +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: +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. +- 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``) +- 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. +Once you have all of those installed, you can install the necessary virtual +environments for this repository using tox. Other tools ########### @@ -33,7 +42,10 @@ 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:: +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 @@ -41,11 +53,19 @@ 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:: +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. +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 ########################### @@ -59,13 +79,15 @@ We group tox environments with the following labels: * ``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: +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. +Running ``tox run -m format`` and ``tox run -m lint`` before committing code is +recommended. Contributing code diff --git a/tox.ini b/tox.ini index e5500e41..01c8e2aa 100644 --- a/tox.ini +++ b/tox.ini @@ -118,5 +118,5 @@ commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --wa [testenv:lint-docs] description = Lint the documentation with sphinx-lint base = docs -commands = sphinx-lint --ignore docs/_build --max-line-length 80 -e all {posargs} docs/ +commands = sphinx-lint --ignore docs/_build --ignore .tox --ignore .venv --ignore venv --max-line-length 80 -e all {posargs} labels = lint