Adding upstream version 0.9.0.upstream/0.9.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

8 files changed, 326 insertions, 0 deletions

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 <https://github.com/pypa/build/>
+   Issue Tracker <https://github.com/pypa/build/issues>
+
+.. _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/