From b49f1524e250764592ff132af8fb0d39182620f7 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 29 Apr 2024 06:20:41 +0200 Subject: Adding upstream version 0.9.0. Signed-off-by: Daniel Baumann --- docs/api.rst | 26 +++++++++++++++++ docs/changelog.rst | 1 + docs/conf.py | 67 ++++++++++++++++++++++++++++++++++++++++++++ docs/differences.rst | 30 ++++++++++++++++++++ docs/index.rst | 54 ++++++++++++++++++++++++++++++++++++ docs/installation.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/mission.rst | 20 +++++++++++++ docs/test_suite.rst | 51 ++++++++++++++++++++++++++++++++++ 8 files changed, 326 insertions(+) create mode 100644 docs/api.rst create mode 120000 docs/changelog.rst create mode 100644 docs/conf.py create mode 100644 docs/differences.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/mission.rst create mode 100644 docs/test_suite.rst (limited to 'docs') diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..254db23 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,26 @@ +API Documentation +================= + +``build`` module +---------------- + +.. automodule:: build + :members: + :undoc-members: + :show-inheritance: + +``build.env`` module +-------------------- + +.. automodule:: build.env + :members: + :undoc-members: + :show-inheritance: + +``build.util`` module +--------------------- + +.. automodule:: build.util + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 120000 index 0000000..e22698b --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1 @@ +../CHANGELOG.rst \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..26e77d0 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,67 @@ +# 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: +# 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 build + + +# -- Project information ----------------------------------------------------- + +project = 'build' +copyright = '2020, Filipe Laíns' +author = 'Filipe Laíns' + +# The short X.Y version +version = build.__version__ +# The full version, including alpha/beta/rc tags +release = build.__version__ + + +# -- 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.intersphinx', + 'sphinx_autodoc_typehints', + 'sphinx_argparse_cli', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), +} + +# 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 = [] + +default_role = 'any' + +# -- 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 = 'furo' +html_title = f'build {version}' + +# 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_static_path = ['_static'] + +autoclass_content = 'both' diff --git a/docs/differences.rst b/docs/differences.rst new file mode 100644 index 0000000..6fbc401 --- /dev/null +++ b/docs/differences.rst @@ -0,0 +1,30 @@ +============================ +Differences from other tools +============================ + +``pep517.build`` +---------------- + +build implements a CLI tailored to end users. + +``pep517.build`` contained a proof-of-concept of a :pep:`517` +frontend. It *"implement[ed] essentially the simplest possible frontend +tool, to exercise and illustrate how the core functionality can be +used"*. It has since been `deprecated and is scheduled for removal`_. + +``setup.py sdist bdist_wheel`` +------------------------------ + +build is roughly the equivalent of ``setup.py sdist bdist_wheel`` but +with :pep:`517` support, allowing use with projects that don't use setuptools. + +.. _deprecated and is scheduled for removal: https://github.com/pypa/pep517/pull/83 + +Custom Behaviors +---------------- + +Fallback Backend +^^^^^^^^^^^^^^^^ + +As recommended in :pep:`517`, if no backend is specified, ``build`` will +fallback to ``setuptools.build_meta:__legacy__``. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f13aa7a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,54 @@ +:hide-toc: + +***** +build +***** + +A simple, correct :pep:`517` build frontend. + +build will invoke the :pep:`517` hooks to build a distribution package. +It is a simple build tool and does not perform any dependency management. + +.. sphinx_argparse_cli:: + :module: build.__main__ + :func: main_parser + :prog: python -m build + :title: python -m build + :usage_width: 97 + +.. note:: + + A ``pyproject-build`` CLI script is also available, so that tools such as pipx_ + can use it. + +By default build will build the package in an isolated +environment, but this behavior can be disabled with ``--no-isolation``. + +.. toctree:: + :hidden: + + mission + differences + +.. toctree:: + :caption: Usage + :hidden: + + installation + changelog + api + +.. toctree:: + :caption: Contributing + :hidden: + + test_suite + +.. toctree:: + :caption: Project Links + :hidden: + + Source Code + Issue Tracker + +.. _pipx: https://github.com/pipxproject/pipx diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..563ff57 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,77 @@ +============ +Installation +============ + +You can download a tarball_ from Github, checkout the latest `git tag`_ or fetch +the artifacts from `project page`_ on PyPI. + +The recommended way is to checkout the git tags, as they are PGP signed with one +of the following keys: + +- |3DCE51D60930EBA47858BA4146F633CBB0EB4BF2|_ *(Filipe Laíns)* + +``build`` may also be installed via `pip`_ or an equivalent: + +.. code-block:: sh + + $ pip install build + +.. tip:: + If you prefer, or are already using virtualenv_ in your workflow, you can + install ``build`` with the optional ``virtualenv`` dependency: + + .. code-block:: sh + + $ pip install 'build[virtualenv]' + + this way, ``build`` will use virtualenv_ for isolation, instead of venv_. + This can be particularly useful, for example, when using automation tools + that rely on virtualenv_, such as tox_, or when your operating system's + Python package does not include venv_ in the standard installation (such as + some versions of Ubuntu). + +Bootstrapping +============= + +This package can build itself with only the ``toml`` and ``pep517`` +dependencies. The ``--skip-dependency-check`` flag should be used in this +case. + +On Python 3.10 and older, we have a dependency on tomli_, but toml_ can be +used instead, which may make bootstrapping easier. + + +Compatibility +============= + +``build`` is verified to be compatible with the following Python +versions: + +- 2.7 +- 3.5 +- 3.6 +- 3.7 +- 3.8 +- 3.9 +- PyPy(2) +- PyPy3 + + +.. _pipx: https://github.com/pipxproject/pipx +.. _pip: https://github.com/pypa/pip +.. _PyPI: https://pypi.org/ + +.. _tox: https://tox.readthedocs.org/ +.. _virtualenv: https://virtualenv.pypa.io +.. _venv: https://docs.python.org/3/library/venv.html + +.. _tarball: https://github.com/pypa/build/releases +.. _git tag: https://github.com/pypa/build/tags +.. _project page: https://pypi.org/project/build/ + +.. _tomli: https://github.com/hukkin/tomli +.. _toml: https://github.com/uiri/toml + + +.. |3DCE51D60930EBA47858BA4146F633CBB0EB4BF2| replace:: ``3DCE51D60930EBA47858BA4146F633CBB0EB4BF2`` +.. _3DCE51D60930EBA47858BA4146F633CBB0EB4BF2: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3dce51d60930eba47858ba4146f633cbb0eb4bf2 diff --git a/docs/mission.rst b/docs/mission.rst new file mode 100644 index 0000000..f83f60e --- /dev/null +++ b/docs/mission.rst @@ -0,0 +1,20 @@ +================= +Mission Statement +================= + +In the Python ecosystem, the build system tools and the package management +are very intertwined. While it might be useful for user to be able to access +all this capabilities in a single project (such as pip_), there are several +use cases where this is not desirable. The main being custom environments +(outside PyPI_) or situations where the user does its own package management, +such as Linux distributions. + +This project aims to fit the "building packages hole" for such use-cases in +:pep:`517`/:pep:`518` workflows. + +As it is intended to be used by users that do their own package management, +we will try to keep dependencies to a minimum, in order to try make +bootstrapping easier. + +.. _pip: https://github.com/pypa/pip +.. _PyPI: https://pypi.org/ diff --git a/docs/test_suite.rst b/docs/test_suite.rst new file mode 100644 index 0000000..d486106 --- /dev/null +++ b/docs/test_suite.rst @@ -0,0 +1,51 @@ +********** +Test Suite +********** + +Due to its nature, ``build`` has a somewhat complex test suite, which we will +try to go through in this document. + +Firstly, there are two set of tests, unit tests and integration tests. In unit +tests, we test the actual code implementation. In integration tests, we test +``build`` on a few real world projects; this is mostly a sanity test. + +Integration tests take a long time to run, and are not very helpful tracking +down issues, so they are **disabled by default**. They can be enabled by passing +either ``--run-integration`` or ``--only-integration`` arguments to pytest, +where the latter will disable the unit tests and only run the integration ones. +Even though these tests are disabled by default, they will be run in CI, +where test suite run durations are not a big issue. + +To run the test suite we use ``tox``, which automates running the test suite on +different environments: + + +.. code-block:: console + + tox + + +You can find out more about how to run ``tox`` and its arguments in the +`tox documentation`_. + +We have a fairly large environment matrix. We run tests for all supported Python +versions and implementations, and with the module being invoked from path, +sdist install, or wheel install. Additionally, we have an environment for type +checking, and one to produce the documentation. There are some other extra +environments, like checking the code with the minimum version of each +dependency. + +Some examples commands for this project: + - Run type checking: ``tox -e type`` + - Only run unit tests against Python 3.9: ``tox -e py39`` + - Run both unit and integration tests: ``tox -- --run-integration`` + - Only run integration tests: ``tox -- --only-integration`` + - Only run integration tests with parallel tasks: ``tox -- -n auto --only-integration`` + - Only run unit tests against Python 3.9 with the module installed via wheel: ``tox -e py39-wheel`` + + +We have CI testing, where we the test suite across all supported operating +systems, and have test coverage reports. + + +.. _tox documentation: https://tox.readthedocs.io/ -- cgit v1.2.3