From d6c148aa4dc8aa78ccdaa2533f8fbad7a07cc7b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filipe=20La=C3=ADns?= Date: Fri, 27 Jan 2023 19:35:57 +0000 Subject: [PATCH] DOC: major documentation rewrite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #197, #230, #253, and #264 Sets us up to fix #138, #233, and #224 Signed-off-by: Filipe Laíns --- README.md | 49 ++- docs/conf.py | 14 + docs/contributing/commit-format.rst | 18 + docs/contributing/documentation.rst | 36 ++ docs/contributing/getting-started.rst | 15 + docs/contributing/test-suite.rst | 16 + docs/explanations/design-old.rst | 86 +++++ docs/explanations/design.rst | 26 ++ docs/explanations/editable-installs.rst | 19 ++ docs/explanations/internal-dependencies.rst | 17 + docs/how-to-guides/add-dependencies.rst | 17 + docs/how-to-guides/build-directory.rst | 18 + docs/how-to-guides/config-settings.rst | 49 +++ docs/how-to-guides/editable-installs.rst | 83 +++++ .../executable-with-internal-dependencies.rst | 24 ++ docs/how-to-guides/first-project.rst | 76 +++++ docs/how-to-guides/meson-args.rst | 21 ++ docs/index.rst | 218 ++++-------- docs/reference/config-settings.rst | 83 +++++ docs/reference/environment-variables.rst | 93 ++++++ docs/reference/limitations.rst | 54 +++ docs/reference/pyproject-settings.rst | 33 ++ docs/reference/quirks.rst | 20 ++ docs/tutorials/data.rst | 20 ++ docs/tutorials/entrypoints.rst | 17 + docs/tutorials/executable.rst | 21 ++ docs/tutorials/introduction.rst | 311 ++++++++++++++++++ docs/usage/build-options.rst | 27 -- docs/usage/specific-behaviors.rst | 36 -- docs/usage/start.rst | 106 ------ pyproject.toml | 2 + 31 files changed, 1285 insertions(+), 340 deletions(-) create mode 100644 docs/contributing/commit-format.rst create mode 100644 docs/contributing/documentation.rst create mode 100644 docs/contributing/getting-started.rst create mode 100644 docs/contributing/test-suite.rst create mode 100644 docs/explanations/design-old.rst create mode 100644 docs/explanations/design.rst create mode 100644 docs/explanations/editable-installs.rst create mode 100644 docs/explanations/internal-dependencies.rst create mode 100644 docs/how-to-guides/add-dependencies.rst create mode 100644 docs/how-to-guides/build-directory.rst create mode 100644 docs/how-to-guides/config-settings.rst create mode 100644 docs/how-to-guides/editable-installs.rst create mode 100644 docs/how-to-guides/executable-with-internal-dependencies.rst create mode 100644 docs/how-to-guides/first-project.rst create mode 100644 docs/how-to-guides/meson-args.rst create mode 100644 docs/reference/config-settings.rst create mode 100644 docs/reference/environment-variables.rst create mode 100644 docs/reference/limitations.rst create mode 100644 docs/reference/pyproject-settings.rst create mode 100644 docs/reference/quirks.rst create mode 100644 docs/tutorials/data.rst create mode 100644 docs/tutorials/entrypoints.rst create mode 100644 docs/tutorials/executable.rst create mode 100644 docs/tutorials/introduction.rst delete mode 100644 docs/usage/build-options.rst delete mode 100644 docs/usage/specific-behaviors.rst delete mode 100644 docs/usage/start.rst diff --git a/README.md b/README.md index e3e9669ac..eea6132e0 100644 --- a/README.md +++ b/README.md @@ -11,29 +11,26 @@ SPDX-License-Identifier: MIT [![codecov](https://codecov.io/gh/mesonbuild/meson-python/branch/main/graph/badge.svg?token=xcb2u2YvVk)](https://codecov.io/gh/mesonbuild/meson-python) [![Documentation Status](https://readthedocs.org/projects/meson-python/badge/?version=stable)](https://meson-python.readthedocs.io/en/stable/?badge=stable) -Python build backend ([PEP 517](https://www.python.org/dev/peps/pep-0517/)) for Meson projects. - -See the [documentation](https://meson-python.readthedocs.io/en/stable/) for more details. - -### Status - -- Pure Python modules :+1: -- Native modules - - Don't link against anything :+1: - - Link against external libraries :+1: - - Link against libraries from the Meson project :+1: - - Detect the ABI :+1: -- Scripts (executables in Meson) - - Don't link against anything :+1: - - Link against external libraries :+1: - - Link against libraries from the Meson project :hammer: - -#### Platform Support - -- Linux :+1: -- Windows :hammer: - - Does not support linking against libraries from the Meson project -- MacOS :hammer: - - Does not support linking against libraries from the Meson project -- Other UNIX-like :warning: - - Most platforms should work, but currently that is not tested or guaranteed +`meson-python` is a Python build backend built on top of the [Meson][meson] +build-system. It enables you to use [Meson][meson] for your Python packages. + +See our [documentation][docs] for more details. + + +## Support + +If you have a general question feel free to [start a discussion][new discussion] +on Github. If you want to report a bug, request a feature, or propose an improvement, feel +free to open an issue on our [bugtracker][bugtracker]. + +## Contributing + +If you are interested in contributing, please check out +[our documentation][contributing docs]. + + +[meson]: https://github.com/mesonbuild/meson +[docs]: https://meson-python.readthedocs.io/en/stable/ +[new discussion]: https://github.com/mesonbuild/meson-python/discussions/new/choose +[bugtracker]: https://github.com/mesonbuild/meson-python/issues +[contributing docs]: https://meson-python.readthedocs.io/en/lastest/contributing/getting-started.html diff --git a/docs/conf.py b/docs/conf.py index 57d506cb9..37f63c8b1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,7 +37,10 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', 'sphinx_autodoc_typehints', + 'sphinx_copybutton', + 'sphinx_design', ] intersphinx_mapping = { @@ -55,6 +58,8 @@ default_role = 'any' +todo_include_todos = True + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -63,6 +68,15 @@ html_theme = 'furo' html_title = f'meson-python {version}' +html_theme_options = { + 'light_css_variables': { + 'font-stack': ( + 'system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,' + 'Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji' + ), + }, +} + # 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'. diff --git a/docs/contributing/commit-format.rst b/docs/contributing/commit-format.rst new file mode 100644 index 000000000..a7115c03b --- /dev/null +++ b/docs/contributing/commit-format.rst @@ -0,0 +1,18 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _contributing-commit-format: + +************* +Commit format +************* + + +.. todo:: + + - Explain is the same as Numpy and SciPy + - List valid prefixes + - Speak a bit about message clarity + - Speak a bit about splitting commits into logical changes + - Mention we require a linear history diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst new file mode 100644 index 000000000..1cb68e576 --- /dev/null +++ b/docs/contributing/documentation.rst @@ -0,0 +1,36 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _contributing-documentation: + +************* +Documentation +************* + +Our documentation is built on sphinx_, is written using reStructuredText_, and +follows the Diátaxis_ framework. + +To automatically re-build the documentation and serve it on an web server, you +can pass the ``serve`` argument to the ``docs`` nox_ task. + + +.. code-block:: console + + $ nox -s docs -- serve + + +When using this argument, the task will watch the documentation source files, +and every time you edit something, it will automatically re-build the +documentation and make it available on the provided web server. + + +.. todo:: + + Elaborate more with tips on how to write. + + +.. _sphinx: https://www.sphinx-doc.org +.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _Diátaxis: https://diataxis.fr/ +.. _nox: https://github.com/wntrblm/nox diff --git a/docs/contributing/getting-started.rst b/docs/contributing/getting-started.rst new file mode 100644 index 000000000..5bce158ac --- /dev/null +++ b/docs/contributing/getting-started.rst @@ -0,0 +1,15 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _contributing-getting-started: + +*************** +Getting started +*************** + + +.. todo:: + + - Introduction to the development workflow. + - ? diff --git a/docs/contributing/test-suite.rst b/docs/contributing/test-suite.rst new file mode 100644 index 000000000..52d68a9d3 --- /dev/null +++ b/docs/contributing/test-suite.rst @@ -0,0 +1,16 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _contributing-test-suite: + +********** +Test suite +********** + + +.. todo:: + + - Introduce nox + - Explain our most relevant pytest fixtures (``package_*``, ``sdist_*``, + ``wheel_*``, ``editable_*``, ``venv``, etc.) diff --git a/docs/explanations/design-old.rst b/docs/explanations/design-old.rst new file mode 100644 index 000000000..d9422dd33 --- /dev/null +++ b/docs/explanations/design-old.rst @@ -0,0 +1,86 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +:orphan: + +.. _explanations-design-old: + +******************************* +How does ``meson-python`` work? +******************************* + + +.. admonition:: Old documentation + :class: attention + + You are looking at the old documentation. We are currently in the process of + refactoring the whole documentation and this page was part of the old + version. While it still contains lots of relevant information, it is not + necessarily in the format we ultimately want to present, and is not well + integrated with the other parts of the documentation. + + + +How does it work? +================= + +We implement the Python build system hooks, enabling any standards compliant +Python tool (pip_, `pypa/build`_, etc.) to build and install the project. + +``meson-python`` will build a Python sdist (source distribution) or +wheel (binary distribution) from Meson_ project. + +Source distribution (sdist) +--------------------------- + +The source distribution is based on ``meson dist``, so make sure all your files +are included there. In git projects, Meson_ will not include files that are not +checked into git, keep that in mind when developing. By default, all files +under version control will be included in the sdist. In order to exclude files, +use ``export-ignore`` or ``export-subst`` attributes in ``.gitattributes`` (see +the ``git-archive`` documentation for details; ``meson dist`` uses +``git-archive`` under the hood). + +Local (uncommitted) changes to files that are under version control will be +included. This is often needed when applying patches, e.g. for build issues +found during packaging, to work around test failures, to amend the license for +vendored components in wheels, etc. + +Binary distribution (wheels) +---------------------------- + +The binary distribution is built by running Meson_ and introspecting the build +and trying to map the files to their correct location. Due to some limitations +and/or bugs in Meson_, we might not be able to map some of the files with +certainty. In these cases, we will take the safest approach and warn the user. +In some cases, we might need to resort to heuristics to perform the mapping, +similarly, the user will be warned. These warnings are not necessarily a reason +for concern, they are there to help identifying issues. In these cases, we +recommend that you check if the files in question were indeed mapped to the +expected place, and open a bug report if they weren't. + +If the project itself includes shared libraries that are needed by other files, +those libraries will be included in the wheel, and native files will have their +library search path extended to include the directory where the libraries are +placed. + +If the project depends on external shared libraries, those libraries will not +be included in the wheel. This can be handled in several ways by the package +developer using ``meson-python``: + +1. Finding or creating a suitable Python package that provides those shared + libraries and can be added to ``dependencies`` in ``pyproject.toml``. +2. Vendoring those libraries into the wheel. Currently ``meson-python`` does + not provide an OS-agnostic way of doing that; on Linux ``auditwheel`` can be + used, and on macOS ``delocate``. Or, the package developer can copy the + shared libraries into the source tree and patch ``meson.build`` files to + include them. +3. Documenting that the dependency is assumed to already be installed on the + end user's system, and letting the end user install it themselves (e.g., + through their Linux distro package manager). + + +.. _pip: https://github.com/pypa/pip +.. _pypa/build: https://github.com/pypa/build +.. _Meson: https://github.com/mesonbuild/meson diff --git a/docs/explanations/design.rst b/docs/explanations/design.rst new file mode 100644 index 000000000..308e75d07 --- /dev/null +++ b/docs/explanations/design.rst @@ -0,0 +1,26 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _explanations-design: + +******************************* +How does ``meson-python`` work? +******************************* + + +.. todo:: + + - Explain how ``meson-python`` maps files to the wheel + + - Link to :ref:`tutorials-executable` in the relevant section + + - Explain why the heuristics are necessary and how they work + - Explain why we don't support ``install_data`` + + - Link to the relevant :ref:`reference-limitations` section + + - ? + + +You can find the old documentation :ref:`here `. diff --git a/docs/explanations/editable-installs.rst b/docs/explanations/editable-installs.rst new file mode 100644 index 000000000..776aec136 --- /dev/null +++ b/docs/explanations/editable-installs.rst @@ -0,0 +1,19 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _explanations-editable-installs: + +****************************** +How do editable installs work? +****************************** + + +.. todo:: + + - Explain how the custom finder works + - Explain what is the purpose of the ``_MESONPY_EDITABLE_SKIP`` environment + variable + + - Warn that the approach described is purely informational, and should + not be relied on diff --git a/docs/explanations/internal-dependencies.rst b/docs/explanations/internal-dependencies.rst new file mode 100644 index 000000000..392156a5f --- /dev/null +++ b/docs/explanations/internal-dependencies.rst @@ -0,0 +1,17 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _explanations-internal-dependencies: + +*************************************** +How do we handle internal dependencies? +*************************************** + + +.. todo:: + + - Explain why bundle internal dependencies + - Explain how we bundle internal dependencies + + - Explain how we patch the ``RPATH`` diff --git a/docs/how-to-guides/add-dependencies.rst b/docs/how-to-guides/add-dependencies.rst new file mode 100644 index 000000000..d204fdb2a --- /dev/null +++ b/docs/how-to-guides/add-dependencies.rst @@ -0,0 +1,17 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-add-dependencies: + +******************* +Adding dependencies +******************* + + +.. todo:: + + - Mention how to add dependencies + - Mention how to add optional dependencies + - Mention how to add build dependencies + - Give a quick introduction to the Python dependency specification format diff --git a/docs/how-to-guides/build-directory.rst b/docs/how-to-guides/build-directory.rst new file mode 100644 index 000000000..d3b8ba98f --- /dev/null +++ b/docs/how-to-guides/build-directory.rst @@ -0,0 +1,18 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-build-directory: + +******************************* +Use a permanent build directory +******************************* + + +.. todo:: + + - Explain why you want to use the ``builddir`` option + - Explain how ``builddir`` works + - Warn that user-configured build directories are not "use at your own risk" + - Warn that ``meson-python`` version mismatches in the build directory can + cause trouble diff --git a/docs/how-to-guides/config-settings.rst b/docs/how-to-guides/config-settings.rst new file mode 100644 index 000000000..63d7c533d --- /dev/null +++ b/docs/how-to-guides/config-settings.rst @@ -0,0 +1,49 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-config-settings: + +************************* +Use build config settings +************************* + +Build config settings are settings you can pass to ``meson-python`` when +building your project. They can be use to customize the build in some aspect. + +The way you specify them depends on which tool you are using, here are the most +popular ones. + + +`pypa/build`_ +============= + +On `pypa/build`_, they can be used via the ``-C``/``--config-setting`` option. + + +.. code-block:: console + + $ python -m build -Ckey=value + + +Please check the `pypa/build documentation`_ for more information. + + +pip_ +==== + +On `pip`_, they can be used via the ``--config-settings`` option. + + +.. code-block:: console + + $ pip install . --config-settings key=value + + +Please check the `pypa/build documentation`_ for more information. + + +.. _pypa/build: https://github.com/pypa/build +.. _pypa/build documentation: https://pypa-build.readthedocs.io/en/stable/ +.. _pip: https://github.com/pypa/pip +.. _pip documentation: https://pip.pypa.io/ diff --git a/docs/how-to-guides/editable-installs.rst b/docs/how-to-guides/editable-installs.rst new file mode 100644 index 000000000..676ba9364 --- /dev/null +++ b/docs/how-to-guides/editable-installs.rst @@ -0,0 +1,83 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-editable-installs: + +***************** +Editable installs +***************** + +We have support for editable installs! To use it, simply pass the +``-e``/``--editable`` option to pip_. + + +.. code-block:: console + + $ pip install -e . + + +This will install the project in the current directory in editable mode. When a +``meson-python`` package is installed in editable mode, it will be re-built the +first time it is imported. That means, the first time you import a module from +your package, it will take a bit longer. + + +.. admonition:: What is the scope of editable installs? + :class: seealso + + The editable installs feature only targets the Python modules of the project. + Metadata-based features, like `entry points`_, and similar mechanisms will + not be updated when using editable installs. This is a limitation of editable + installs specification itself. + + +.. _how-to-guides-editable-installs-verbose: + +Verbose mode +============ + +It might be useful for you to see the output of Meson_ when the package is being +re-built. We provide a *verbose mode* that does this, and can be enabled either +temporarily, after the install, or permanently, in the install. + + +Enable it temporarily +--------------------- + +To enable the verbose mode on any existing ``meson-python`` editable install, +you simply need to set the ``MESONPY_EDITABLE_VERBOSE`` environment variable +to any non-null value. + + +.. code-block:: console + + $ MESONPY_EDITABLE_VERBOSE=1 python + + +Enable it permanently +--------------------- + +To enable verbose mode permanently, you simply need to set the +``editable-verbose`` :ref:`config setting ` to any +non-null value when installing the package. + +With pip_, you can do this as follows: + + +.. code-block:: console + + $ python -m pip install -e . --config-settings editable-verbose=true + + +.. admonition:: ``MESONPY_EDITABLE_VERBOSE`` will have no effect here + :class: attention + + Please note that the ``MESONPY_EDITABLE_VERBOSE`` environment variable will + not have **any** effect on the installation, it simply forces verbose mode to + be enabled **after** the package has been installed. + + +.. _entry points: https://packaging.python.org/en/latest/specifications/entry-points/ +.. _pip: https://github.com/pypa/pip +.. _Meson: https://github.com/mesonbuild/meson diff --git a/docs/how-to-guides/executable-with-internal-dependencies.rst b/docs/how-to-guides/executable-with-internal-dependencies.rst new file mode 100644 index 000000000..6ac60f155 --- /dev/null +++ b/docs/how-to-guides/executable-with-internal-dependencies.rst @@ -0,0 +1,24 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-executable-with-internal-dependencies: + +************************************* +Executable with internal dependencies +************************************* + + +.. todo:: + + - Mention our limitation regarding executables with internal dependencies + + - Link to the relevant :ref:`reference-limitations` section + + - Explain how to work around it (using a static library) + + - Mention how the ``pyproject.toml`` settings can be used to only enable + the workaround on meson-python builds (by adding a custom Meson option + and enabling it on meson-python builds) + + - Link to :ref:`reference-pyproject-settings` diff --git a/docs/how-to-guides/first-project.rst b/docs/how-to-guides/first-project.rst new file mode 100644 index 000000000..64fa36556 --- /dev/null +++ b/docs/how-to-guides/first-project.rst @@ -0,0 +1,76 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-first-project: + +************* +First project +************* + + +.. admonition:: Advanced guide + :class: caution + + This guide assumes you are already familiarized with Python packaging! If you + aren't, we recommend you check our :ref:`tutorial-introduction` tutorial + instead. + + +Specifying the backend +====================== + +Our build backend is called ``mesonpy``, and that's you should specify in the +``build-system.build-backend`` key of ``pyproject-toml``. + +You should need to add ``meson-python``, and all other build dependencies (eg. +Cython_) needed by your Meson_ project, in the ``build-system.requires`` key. + + +Example +------- + +.. code-block:: toml + :caption: pyproject.toml + + [build-system] + build-backend = 'mesonpy' + requires = ['meson-python', 'cython'] + + +Specifying the project metadata +=============================== + +We use the standard metadata format in the ``project`` section of +``pyproject.toml``. + +Please refer to the `relevant PyPA documentation page`_ for a full +specification. + + +Example +======= + + +.. code-block:: toml + :caption: pyproject.toml + + [build-system] + build-backend = 'mesonpy' + requires = ['meson-python', 'cython'] + + [project] + name = 'example-package' + version = '1.0.0' + description = 'Our example package using meson-python!' + readme = 'README.md' + requires-python = '>=3.8' + license = {file = 'LICENSE.txt'} + authors = [ + {name = 'Bowsette Koopa', email = 'bowsette@example.com'}, + ] + + +.. _Cython: https://github.com/cython/cython +.. _Meson: https://mesonbuild.com/ +.. _relevant PyPA documentation page: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/ diff --git a/docs/how-to-guides/meson-args.rst b/docs/how-to-guides/meson-args.rst new file mode 100644 index 000000000..752f60e67 --- /dev/null +++ b/docs/how-to-guides/meson-args.rst @@ -0,0 +1,21 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-meson-args: + +*************************** +Passing arguments to Meson_ +*************************** + + +.. todo:: + + - Explain how you can add extra Meson arguments via ``pyproject.toml`` + - Explain how you can add extra Meson arguments via the build conifig + settings + - Mention the order in which Meson arguments are added, and how it affect + Meson + + +.. _Meson: https://github.com/mesonbuild/meson diff --git a/docs/index.rst b/docs/index.rst index 77fe7fb34..13b4f1f5a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,6 @@ .. .. SPDX-License-Identifier: MIT -:hide-toc: ************************* meson-python |PyPI badge| @@ -13,11 +12,6 @@ meson-python |PyPI badge| :alt: pre-commit.ci status -.. image:: https://github.com/mesonbuild/meson-python/actions/workflows/checks.yml/badge.svg - :target: https://github.com/mesonbuild/meson-python/actions/workflows/checks.yml - :alt: Github Action 'checks' workflow status - - .. image:: https://github.com/mesonbuild/meson-python/actions/workflows/tests.yml/badge.svg :target: https://github.com/mesonbuild/meson-python/actions/workflows/tests.yml :alt: Github Action 'tests' workflow status @@ -28,188 +22,117 @@ meson-python |PyPI badge| :alt: Codecov coverage status -Python build backend (PEP 517) for Meson_ projects. - -It enables Python package authors to use Meson_ as the build backend for their -packages. +.. image:: https://readthedocs.org/projects/meson-python/badge/?version=stable + :target: https://meson-python.readthedocs.io/en/stable/?badge=stable + :alt: Documentation Status -How to use? -=========== +.. highlights:: -Please see `getting started`_ for intructions on how to setup your project. + ``meson-python`` is a Python build backend built on top of the Meson_ + build-system. It enables you to use Meson_ for your Python packages. -After setting it up, you can use `pypa/build`_ to build the distribution -artifacts. +Where to start? +=============== -.. code-block:: - python -m build +New to Python packaging +----------------------- +If you are new to Python packaging, we recommend you check our +:ref:`tutorial-introduction` tutorial, which walks you through creating and +releasing your first Python package. -We provide a couple configuration options that should be exposed via the build -frontend, like ``builddir``, to specify the build directory to use/re-use. You -can find more information about them in the `build options page`_. - -Editable installs +Experienced users ----------------- -Editable installs allow you to install the project in such a way where you can -edit the project source and have those changes be reflected in the installed -module, without having to explicitly rebuild and reinstall. - -The way it works on ``meson-python`` specifically, is that when you import a -module of the project, it will be rebuilt on the fly. This means that project -imports will take more time than usual. - -You can use pip to install the project in editable mode. - - -.. code-block:: - - python -m pip install -e . - - -It might be helpful to see the output of the Meson_ commands. This is offered -as a **provisional** feature, meaning it is subject to change. - -If you want to temporarily enable the output, you can set the -``MESONPY_EDITABLE_VERBOSE`` environment variable to a non-empty value. If this -environment variable is present during import, the Meson_ commands and their -output will be printed. - - -.. code-block:: - - MESONPY_EDITABLE_VERBOSE=1 python my_script.py - - - -This behavior can also be enabled by default by passing the ``editable-verbose`` -config setting when installing the project. - - -.. code-block:: - - python -m pip install -e . --config-settings editable-verbose=true +If you are already familiarized with Python packaging, we recommend you check +our :ref:`how-to-guides-first-project` guide, which shows you how to quickly +setup a ``meson-python`` project. -This way, you won't need to always set ``MESONPY_EDITABLE_VERBOSE`` environment -variable, the Meson_ commands and their output will always be printed. +How to reach us? +================ -The ``MESONPY_EDITABLE_VERBOSE`` won't have any effect during the project -install step. +``meson-python`` is an open source project, so all support is at a best-effort +capacity, but we are happy to help where we can. +If you have a general question feel free to `start a discussion`_ on Github. If +you want to report a bug, request a feature, or propose an improvement, feel +free to open an issue on our bugtracker_. -How does it work? -================= -We implement the Python build system hooks, enabling any standards compliant -Python tool (pip_, `pypa/build`_, etc.) to build and install the project. +.. admonition:: Search first! + :class: tip -``meson-python`` will build a Python sdist (source distribution) or -wheel (binary distribution) from Meson_ project. + Before starting a discussion, please try searching our bugtracker_ and + `discussion page`_ first. -Source distribution (sdist) ---------------------------- -The source distribution is based on ``meson dist``, so make sure all your files -are included there. In git projects, Meson_ will not include files that are not -checked into git, keep that in mind when developing. By default, all files -under version control will be included in the sdist. In order to exclude files, -use ``export-ignore`` or ``export-subst`` attributes in ``.gitattributes`` (see -the ``git-archive`` documentation for details; ``meson dist`` uses -``git-archive`` under the hood). +In addition, the `#meson-python`_ channel on the `PyPA Discord`_ may be useful +for quick questions - one ``meson-python`` maintainer is active there. -Local (uncommitted) changes to files that are under version control will be -included. This is often needed when applying patches, e.g. for build issues -found during packaging, to work around test failures, to amend the license for -vendored components in wheels, etc. - -Binary distribution (wheels) ----------------------------- - -The binary distribution is built by running Meson_ and introspecting the build -and trying to map the files to their correct location. Due to some limitations -and/or bugs in Meson_, we might not be able to map some of the files with -certainty. In these cases, we will take the safest approach and warn the user. -In some cases, we might need to resort to heuristics to perform the mapping, -similarly, the user will be warned. These warnings are not necessarily a reason -for concern, they are there to help identifying issues. In these cases, we -recommend that you check if the files in question were indeed mapped to the -expected place, and open a bug report if they weren't. - -If the project itself includes shared libraries that are needed by other files, -those libraries will be included in the wheel, and native files will have their -library search path extended to include the directory where the libraries are -placed. - -If the project depends on external shared libraries, those libraries will not -be included in the wheel. This can be handled in several ways by the package -developer using ``meson-python``: - -1. Finding or creating a suitable Python package that provides those shared - libraries and can be added to ``dependencies`` in ``pyproject.toml``. -2. Vendoring those libraries into the wheel. Currently ``meson-python`` does - not provide an OS-agnostic way of doing that; on Linux ``auditwheel`` can be - used, and on macOS ``delocate``. Or, the package developer can copy the - shared libraries into the source tree and patch ``meson.build`` files to - include them. -3. Documenting that the dependency is assumed to already be installed on the - end user's system, and letting the end user install it themselves (e.g., - through their Linux distro package manager). - - -What are the limitations? -========================= +.. toctree:: + :caption: Release + :hidden: -Not yet supported ------------------ + changelog -Platform -~~~~~~~~ +.. toctree:: + :caption: Tutorials + :hidden: -Windows and MacOS are not yet fully supported, but that is actively being worked on. + tutorials/introduction + tutorials/data + tutorials/entrypoints + tutorials/executable -Executables that link against project libraries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :caption: How to guides + :hidden: -If you have an executable in your project that links against a shared library -that is shipped by your project, ``meson-python`` will not be able to correctly -bundle it to the wheel. The executable will be included in the wheel, but it -will not be able to find the project librar(y/ies) it links against. + how-to-guides/first-project + how-to-guides/add-dependencies + how-to-guides/editable-installs + how-to-guides/config-settings + how-to-guides/meson-args + how-to-guides/build-directory + how-to-guides/executable-with-internal-dependencies -No data -------- +.. toctree:: + :caption: Reference + :hidden: -Data (see |install_data|_) is not supported by the wheel standard. Project -should install data as Python source instead (Python source does not have to be -only Python files!) and use :py:mod:`importlib.resources` (or the -:py:mod:`importlib_resources` backport) to access the data. -If you really need the data to be installed where it was previously (eg. -``/usr/data``), you can do so at runtime. + reference/config-settings + reference/pyproject-settings + reference/environment-variables + reference/quirks + reference/limitations .. toctree:: - :caption: Usage + :caption: Explanations :hidden: - usage/start - usage/build-options - usage/specific-behaviors + explanations/design + explanations/internal-dependencies + explanations/editable-installs .. toctree:: - :caption: Release + :caption: Contributing :hidden: - changelog + contributing/getting-started + contributing/commit-format + contributing/test-suite + contributing/documentation .. toctree:: @@ -231,5 +154,10 @@ If you really need the data to be installed where it was previously (eg. .. _pypa/build: https://github.com/pypa/build .. _build options page: usage/build-options.html .. _install_data: https://mesonbuild.com/Reference-manual_functions.html#install_data +.. _start a discussion: https://github.com/mesonbuild/meson-python/discussions/new/choose +.. _bugtracker: https://github.com/mesonbuild/meson-python/issues +.. _discussion page: https://github.com/mesonbuild/meson-python/discussions +.. _#meson-python: https://discord.com/channels/803025117553754132/1040322863930024057 +.. _PyPA Discord: https://discord.gg/pypa .. |install_data| replace:: ``install_data`` diff --git a/docs/reference/config-settings.rst b/docs/reference/config-settings.rst new file mode 100644 index 000000000..5a05a3384 --- /dev/null +++ b/docs/reference/config-settings.rst @@ -0,0 +1,83 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _reference-config-settings: + +********************* +Build config settings +********************* + +This page lists the build configuration settings, that is, the settings you can +pass when building the project. Please check our +:ref:`how-to-guides-config-settings` guide for information on how to use them. + + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + :stub-columns: 1 + + * - Setting name + - Description + + * - ``builddir`` + - Selects the Meson_ build directory to use. If the directory already + exists, it will be re-used, if it does not exists, it will be created. + This lets you avoid rebuilding the whole project from scratch when + developing. It is also useful if you want to configure the build + yourself. + + .. admonition:: Use at your own risk + :class: warning + + Re-using a build directory that was not configured by ``meson-python`` + can cause issues, so use at your own risk. We cannot fully support + this use-case, but will try to fix issues where possible and + reasonably viable. + + Passing this option with a non-existent build directory, letting + ``meson-python`` configure it, and then passing it again on subsequent + builds, is perfectly fine. Just be sure to delete the build directory + after changing the ``meson-python`` version, as that might cause + issues. + + * - ``dist-args`` + - Extra arguments to be passed to the ``meson dist`` command. The arguments + are placed after the :ref:`reference-pyproject-settings` ones. + + * - ``setup-args`` + - Extra arguments to be passed to the ``meson setup`` command. The + arguments are placed after the :ref:`reference-pyproject-settings` ones. + + * - ``compile-args`` + - Extra arguments to be passed to the ``meson compile`` command. The + arguments are placed after the :ref:`reference-pyproject-settings` ones. + + * - ``install-args`` + - Extra arguments to be passed to the ``meson install`` command. The + arguments are placed after the :ref:`reference-pyproject-settings` ones. + + * - ``editable-verbose`` + - Enable :ref:`verbose mode ` on + editable an install. + + .. admonition:: Only valid on editable installs + :class: attention + + This option is only valid when building the project for an editable + install. Please check our :ref:`how-to-guides-editable-installs` guide + for more information. + + +.. admonition:: Check our guides + :class: seealso + + Check our guides to learn more about how to use these settings: + + - :ref:`how-to-guides-build-directory` + - :ref:`how-to-guides-meson-args` + - :ref:`how-to-guides-editable-installs` + + +.. _Meson: https://github.com/mesonbuild/meson diff --git a/docs/reference/environment-variables.rst b/docs/reference/environment-variables.rst new file mode 100644 index 000000000..62fa4231f --- /dev/null +++ b/docs/reference/environment-variables.rst @@ -0,0 +1,93 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _reference-environment-variables: + +********************* +Environment variables +********************* + + +.. todo:: + + - Document ``ARCHFLAGS`` (see `#226`_) + + +.. list-table:: + :widths: 35 65 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + + * - ``NO_COLOR`` + - Disables color output from messages by ``meson-python``.See + https://no-color.org for more information. + + .. admonition:: Conflicts with other options + :class: attention + + Cannot be used at the same time as ``FORCE_COLOR``. + + * - ``FORCE_COLOR`` + - Forces color output from messages by ``meson-python``. + + .. admonition:: Conflicts with other options + :class: attention + + Cannot be used at the same time as ``NO_COLOR``. + + * - ``MESONPY_EDITABLE_VERBOSE`` + - Enables verbose output in editable installs. + + .. admonition:: Check our guide + :class: seealso + + Please check our :ref:`how-to-guides-editable-installs` guide for more + information on how to use it. + + * - ``MACOS_DEPLOYMENT_TARGET`` + - Specify the target macOS version. + + If ``MACOSX_DEPLOYMENT_TARGET`` is set, we will use the selected version + for the *wheel* tag. + + .. admonition:: Use the right version + :class: attention + + Please use major versions only, so ``10.13``, ``11``, ``12``. + + If ``MACOSX_DEPLOYMENT_TARGET`` is not set, the current macOS major + version on the build machine will be used instead (derived from + :py:meth:`platform.mac_ver`). + + .. admonition:: macOS versioning + :class: note + + macOS versioning changed from macOS 11 onwards. For macOS 10.x, the + versioning scheme is ``10.major.minor``. From macOS 11, it is + ``major.minor.bugfix``. Wheel tags and deployment targets are currently + designed to be for major versions only. Examples of the platform part + of tags that are currently accepted by, e.g., ``pip`` are: + ``macosx_10_9``, ``macosx_10_13``, ``macosx_11_0``, ``macosx_12_0``. + + .. admonition:: Specifying the target version via the compiler + :class: note + + Another way of specifying the target macOS platform is to explicitly + use ``-mmacosx-version-min`` compile and link flags when invoking + Clang_ or GCC_. It is not possible for ``meson-python`` to detect this + though, so it will not set the *wheel* tag to that flag automatically. + + * - ``NINJA`` + - Specify the ninja_ executable to use. Can also be used to select ninja_ + alternatives like samurai_. + + +.. _#226: https://github.com/mesonbuild/meson-python/pull/226 +.. _Clang: https://clang.llvm.org +.. _GCC: https://gcc.gnu.org +.. _ninja: https://ninja-build.org +.. _samurai: https://github.com/michaelforney/samurai diff --git a/docs/reference/limitations.rst b/docs/reference/limitations.rst new file mode 100644 index 000000000..d4043e802 --- /dev/null +++ b/docs/reference/limitations.rst @@ -0,0 +1,54 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _reference-limitations: + +*********** +Limitations +*********** + + +No data +======= + +Data, as installed by |install_data|_, is not supported. + +We recommend you install your data inside a Python module and use +:py:mod:`importlib.resources` (or the :py:mod:`importlib_resources` backport) to +access it. You can check our :ref:`tutorials-data` tutorial for how to do this. + +If you really need the data to be installed where it was previously (eg. +``/usr/data``), you can do so at runtime. + + +Parallel use of editable installs +================================= + +Currently, using a package installed in editable mode in more than one +interpreter instances at the same time is not supported. + + +Platform-specific limitations +============================= + + +Executables with internal dependencies :bdg-warning:`Windows` :bdg-warning:`macOS` +---------------------------------------------------------------------------------- + + +If you have an executable that links against a shared library provided by your +project, on Windows and macOS ``meson-python`` will not be able to correctly +bundle it into the *wheel*. + +The executable will be included in the *wheel*, but it +will not be able to find the project libraries it links against. + +This is, however, easily solved by using a static library for the executable in +question. Find how to do this in our +:ref:`how-to-guides-executable-with-internal-dependencies` guide. + + +.. _install_data: https://mesonbuild.com/Reference-manual_functions.html#install_data + +.. |install_data| replace:: ``install_data`` diff --git a/docs/reference/pyproject-settings.rst b/docs/reference/pyproject-settings.rst new file mode 100644 index 000000000..1c6b5aa9a --- /dev/null +++ b/docs/reference/pyproject-settings.rst @@ -0,0 +1,33 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _reference-pyproject-settings: + +*************************** +``pyproject.toml`` settings +*************************** + +This page lists the configuration settings supported by ``meson-python`` in the +``pyproject.toml`` file. + + +.. list-table:: + :widths: 35 65 + :header-rows: 1 + :stub-columns: 1 + + * - Setting name + - Description + + * - ``tool.meson-python.args.dist`` + - Extra arguments to be passed to the ``meson dist`` command + + * - ``tool.meson-python.args.setup`` + - Extra arguments to be passed to the ``meson setup`` command. + + * - ``tool.meson-python.args.compile`` + - Extra arguments to be passed to the ``meson compile`` command. + + * - ``tool.meson-python.args.install`` + - Extra arguments to be passed to the ``meson install`` command. diff --git a/docs/reference/quirks.rst b/docs/reference/quirks.rst new file mode 100644 index 000000000..a0ce851b6 --- /dev/null +++ b/docs/reference/quirks.rst @@ -0,0 +1,20 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _reference-quirks: + +****** +Quirks +****** + +.. todo:: + + - Document requirements on how ``import('python').find_installation()`` is + called (see `#233`_) + - Document that Meson, and thus meson-python, require MSVC compilers to be + found in ``$PATH`` on Windows (see `#224`_) + + +.. _#233: https://github.com/mesonbuild/meson-python/issues/233 +.. _#224: https://github.com/mesonbuild/meson-python/issues/224 diff --git a/docs/tutorials/data.rst b/docs/tutorials/data.rst new file mode 100644 index 000000000..2eeba50c7 --- /dev/null +++ b/docs/tutorials/data.rst @@ -0,0 +1,20 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _tutorials-data: + +**************** +Using data files +**************** + + +.. todo:: + + - Explain that meson-python doesn't support ``install_data`` + + - Link to the relevant :ref:`reference-limitations` section + + - Give a quick introduction on the ``importlib.resources`` API + + - Mention the ``importlib_resources`` backport diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst new file mode 100644 index 000000000..71abcdd3b --- /dev/null +++ b/docs/tutorials/entrypoints.rst @@ -0,0 +1,17 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _tutorials-entrypoints: + +************ +Entry points +************ + + +.. todo:: + + - Mention what is the purpose of entry points + - Give an example of a console entry point + - Give an example of a custom entry point + - Mention pluggy maybe for an example use-case? diff --git a/docs/tutorials/executable.rst b/docs/tutorials/executable.rst new file mode 100644 index 000000000..7eefe52ad --- /dev/null +++ b/docs/tutorials/executable.rst @@ -0,0 +1,21 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _tutorials-executable: + +********** +Executable +********** + + +.. todo:: + + - Give an example of how to build an executable in Meson + - Show where the executable gets mapped to inside a wheel + - Link to relevant :ref:`explanations-design` section + - Mention the limitation regarding internal dependencies + + - Link to the relevant :ref:`reference-limitations` section + - Link to the :ref:`how-to-guides-executable-with-internal-dependencies` + guide diff --git a/docs/tutorials/introduction.rst b/docs/tutorials/introduction.rst new file mode 100644 index 000000000..1e57c2a1c --- /dev/null +++ b/docs/tutorials/introduction.rst @@ -0,0 +1,311 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _tutorial-introduction: + +****************************************************** +Introduction to Python packaging with ``meson-python`` +****************************************************** + +If you are new to Python packaging, don't worry! + +We will give you a quick introduction to what steps releasing a Python package +consists of, and walk you through them to get started. + + +Create a Meson_ project +======================= + +To get started, we need a project to publish. As ``meson-python`` is built on +top of Meson, we will create a really simple Meson project. You may already have +a Meson project you wish to publish, in that case, you can simply skip this +step. + + +The module +---------- + +First, we create a simple Python module. We will go for a native module, as +that's really where ``meson-python`` shines against other Python build backends. + + +.. code-block:: c + :caption: our_first_module.c + + #include + + static PyObject* foo(PyObject* self) + { + return PyUnicode_FromString("bar"); + } + + static PyMethodDef methods[] = { + {"foo", (PyCFunction)foo, METH_NOARGS, NULL}, + {NULL, NULL, 0, NULL}, + }; + + static struct PyModuleDef module = { + PyModuleDef_HEAD_INIT, + "our_first_module", + NULL, + -1, + methods, + }; + + PyMODINIT_FUNC PyInit_our_first_module(void) + { + return PyModule_Create(&module); + } + + +Here, we have a create a small module named ``our_first_module``, which has a +function ``foo`` that simply returns ``"bar"``. + + +.. admonition:: Using the C API + :class: seealso + + If you need help writing a native module using Python's C API, we recommend + checking out the following resources. + + `The official Python C API reference manual `_ + `RealPython's "Building a Python C Extension Module" introductory tutorial `_ + `pysheeet's "C Extensions" page `_ + `pysheeet-kr's "Python C API cheatsheet" page `_ + + +The Meson build description +--------------------------- + +Now, we need to create the Meson build description file. This tells Meson what +we want it to build, and how to do it. + + +.. code-block:: meson + :caption: meson.build + + project('purelib-and-platlib', 'c') + + py_mod = import('python') + py = py_mod.find_installation() + + py.extension_module( + 'our_first_module', 'our_first_module.c', + install: true, + ) + + +Here, we use the `Meson Python module`_ to build our ``our_first_module`` +module. We make sure to install it, by passing ``install: true`` to +``extension_module``, as ``meson-python`` will only include in the binary +distribution artifacts targets that Meson would install onto system. Having non +installed targets allows you to build targets for use within the build, or for +tests. + + +Define the Python build system +============================== + +Now, we need to tell Python packaging tooling what build backend to use to build +our package. We do this by creating a ``build-system`` section in the +``pyproject.toml`` file, which is the file used to configure Python packaging +tooling. + +Inside the ``build-system`` section, we need to define two keys, +``build-backend`` and ``requires``. ``build-backend`` defines which build +backend should be used for the project, in meson-python it should always have +the value of ``mesonpy``. ``requires`` lets us specify which packages need to be +installed for the build process, it should include ``meson-python`` and any +other dependencies you might need (eg. ``Cython``), in our case it's just +``meson-python``. + + +.. code-block:: toml + :caption: pyproject.toml + + [build-system] + build-backend = 'mesonpy' + requires = ['meson-python'] + + +After we specify which backend to use, we'll want to define the package +metadata. This is done in the ``project`` section, and the format is pretty +self-explanatory by looking at our example. + + +.. code-block:: toml + :caption: pyproject.toml + + ... + + [project] + name = 'our-first-project' + version = '0.0.1' + description = 'Our first Python project, using meson-python!' + readme = 'README.md' + requires-python = '>=3.8' + license = {file = 'LICENSE.txt'} + authors = [ + {name = 'Bowsette Koopa', email = 'bowsette@example.com'}, + ] + + +.. admonition:: Adding dependencies + :class: seealso + + If you need to add dependencies to the project metadata, you can check our + :ref:`how-to-guides-add-dependencies` guide. + + +.. admonition:: Declaring project metadata + :class: seealso + + Our example doesn't make use of all the fields available, so we recommend you + check out the `PyPA documentation on project metadata`_. + + +.. admonition:: Writing TOML + :class: seealso + + If you are not familiar with the TOML configuration language or need some + help, be sure to check out + `their documentation `__. + + +Generating the distribution artifacts +===================================== + +Now that we have a valid Python project, we can release it. + +To release the project we first need to generate the distribution artifacts, +these are files in a standardized format that Python package installers +understand. There are two kind of artifacts, `source distributions`_, which are +commonly referred to as *sdists*, and `binary distributions`_, which use a +custom format named *wheel*, so they're generally referred to as *wheels*. + + +What are the roles of *sdists* and *wheels* +------------------------------------------- + + +As you might have figured out by the name, *sdists* contain the source code of +the project, and *wheels* contain a compiled [#pure-wheels]_ version of the +project, ready to be copied to the filesystem. + +If your project has compiled code, its *wheels* will be platform-dependent, and +if it has native Python modules, the *wheels* will also be Python version +specific, as the native Python modules depend on the Python ABI. +FIXME(this seems *a bit* convoluted, it isn't awful, but I feel like it could +be simplified or explained in a more natural way) + +Strictly speaking, you don't need to distribute *wheels*, however they make the +user experience much nicer. Unless you have any reason not to, we highly +recommend you distribute *wheels* for at least the most common systems. When +*wheels* are not available for a system, the project can still be installed, be +it needs to be build from the *sdist*, which involves fetching all the build +dependencies and going through the likely expensive build. +FIXME(strictly speaking -- this doesn't sound great, how do we highlight the +importance of building wheels in a better sounding way?) + + +.. [#pure-wheels] + + Projects that don't have any compiled code will have a platform-independent + -- *pure* -- wheel. + + +Building the project +-------------------- + +To generate the distribution artifacts we will use the `pypa/build`_ tool. It +will create a temporary virtual environment, install all the required build +dependencies, and ask ``meson-python`` to build the artifacts. + + +.. code-block:: console + + $ pip install build + $ python -m build + + +If the build succeeded, you'll have the binary artifacts in the ``dist`` folder. + + +.. admonition:: Check the pypa/build documentation + :class: seealso + + To learn more about `pypa/build`_, you can check + `their documentation `__. + + +.. admonition:: Building wheels for many systems + :class: tip + + To build *wheels* for multiple platforms and Python versions, we recommend + you check out the cibuildwheel_ project. + + +Distributing the project +======================== + +Now that we have the distribution artifacts, we can upload them to a repository. +We will upload them to the `Python Package Index`_ (abv. *PyPI*, +`pronounced "pie pea eye"`_), which is repository that comes enabled by default +in most tools. + +For this, we will use Twine_. + + +.. code-block:: console + + $ pip install twine + $ twine upload dist/* + + +.. admonition:: Upload to the `Test PyPI`_ + :class: tip + + If you don't want to upload to the real index, you can upload to the + `Test PyPI`_ instead. + + + .. code-block:: console + + $ twine upload -r testpypi dist/* + + + You can find more about how to use the `Test PyPI`_ in + `its PyPA documentation page `_. + + +.. admonition:: Check the twine documentation + :class: seealso + + To learn more about Twine_, you can check + `their documentation `__. + + +After this, your package should be available on PyPI_, and installable with +pip_. + + +.. code-block:: console + + $ pip install our-first-project + + + +.. _Meson: https://github.com/mesonbuild/meson +.. _Meson Python module: https://mesonbuild.com/Python-module.html +.. _PyPA documentation on project metadata: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/ +.. _source distributions: https://packaging.python.org/en/latest/specifications/source-distribution-format/ +.. _binary distributions: https://packaging.python.org/en/latest/specifications/binary-distribution-format/ +.. _pypa/build: https://github.com/pypa/build +.. _cibuildwheel: https://github.com/pypa/cibuildwheel +.. _Python Package Index: https://pypi.org/ +.. _pronounced "pie pea eye": https://pypi.org/help/#pronunciation +.. _Twine: https://github.com/pypa/twine +.. _Test PyPI: https://test.pypi.org/ +.. _PyPI: https://pypi.org/ +.. _pip: https://github.com/pypa/pip diff --git a/docs/usage/build-options.rst b/docs/usage/build-options.rst deleted file mode 100644 index 8649c1a06..000000000 --- a/docs/usage/build-options.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. SPDX-FileCopyrightText: 2022 The meson-python developers -.. -.. SPDX-License-Identifier: MIT - -************* -Build options -************* - -``builddir`` -============ - -The ``builddir`` option allows the user to specify the build directory to use -for the Meson project. It takes the target path as an argument. If the path -exists, it will be used, if not, it will be created. - - -Example -------- - -.. code-block:: bash - - $ python -m build -Cbuilddir=build - # The `build` directory will be created and used to build the project. - ... - $ python -m build -Cbuilddir=build - # The `build` directory, which already exists, will be re-used, speeding up the build a little. - ... diff --git a/docs/usage/specific-behaviors.rst b/docs/usage/specific-behaviors.rst deleted file mode 100644 index c3cc591eb..000000000 --- a/docs/usage/specific-behaviors.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. SPDX-FileCopyrightText: 2022 The meson-python developers -.. -.. SPDX-License-Identifier: MIT - -****************** -Specific Behaviors -****************** - -This page documents how our backend handles certain situations. - - -``MACOSX_DEPLOYMENT_TARGET`` -============================ - - -.. note:: - - macOS versioning changed from macOS 11 onwards. For macOS 10.x, the - versioning scheme is ``10.major.minor``. From macOS 11, it is - ``major.minor.bugfix``. Wheel tags and deployment targets are currently - designed to be for major versions only. Examples of the platform part - of tags that are currently accepted by, e.g., ``pip`` are: - ``macosx_10_9``, ``macosx_10_13``, ``macosx_11_0``, ``macosx_12_0``. - -The target macOS version can be changed by setting the -``MACOSX_DEPLOYMENT_TARGET`` environment variable. - -If ``MACOSX_DEPLOYMENT_TARGET`` is set, we will use the selected version for the -wheel tag. Please use major versions only, so ``10.13``, ``11``, ``12``. -If ``MACOSX_DEPLOYMENT_TARGET`` is not set, the current macOS major version on -the build machine will be used instead (derived from ``platform.mac_ver()``). - -Note that another way of specifying the target macOS platform is to explicitly -use ``-mmacosx-version-min`` compile and link flags when invoking Clang or GCC. -It is not possible for ``meson-python`` to detect this though, so it will not -set the wheel tag to that flag automatically. diff --git a/docs/usage/start.rst b/docs/usage/start.rst deleted file mode 100644 index 47f25dc2c..000000000 --- a/docs/usage/start.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. SPDX-FileCopyrightText: 2022 The meson-python developers -.. -.. SPDX-License-Identifier: MIT - -*************** -Getting started -*************** - - -Enabling the build backend -========================== - -To use this build backend, you must specify it in your ``pyproject.toml`` file. - -.. code-block:: toml - - [build-system] - build-backend = 'mesonpy' - requires = [ - 'meson-python', - ] - - -If you have any other build dependencies, you must also add them to the -``requires`` list. - - -Metadata -======== - - -Specifying the project metadata -------------------------------- - -We support specifying Python package metadata in the ``project`` table in -``pyproject.toml`` (:pep:`621`). - -To do so, you just need to add a ``project`` section with the details you want -to specify (see :pep:`621` for the specification of the format). - - -.. code-block:: toml - - ... - - [project] - name = 'orion' - version = '1.2.3' - description = 'The Orion constellation!' - readme = 'README.md' - license = { file = 'LICENSE' } - keyword = ['constellation', 'stars', 'sky'] - authors = [ - { name = 'Filipe Laíns', email = 'lains@riseup.net' }, - ] - classifiers = [ - 'Development Status :: 4 - Beta', - 'Programming Language :: Python', - ] - - requires-python = '>=3.7' - dependencies = [ - 'stars >= 1.0.0', - 'location < 3', - ] - - [project.optional-dependencies] - test = [ - 'pytest >= 3', - 'telescope', - ] - - [project.urls] - homepage = 'https://constellations.example.com/orion' - repository = 'https://constellations.example.com/orion/repo' - documentation = 'https://constellations.example.com/orion/docs' - changelog = 'https://constellations.example.com/orion/docs/changelog.html' - - -In case you want us to detect the version automatically from Meson, you can omit -the ``version`` field and add it to ``project.dynamic``. - -.. code-block:: toml - - ... - - [project] - name = 'orion' - dynamic = [ - 'version', - ] - ... - - -Automatic metadata ------------------- - -If ``project`` metadata table is not specified, ``meson-python`` will -fetch the project name and version from Meson. In which case, you -don't need to add anything else to your ``pyproject.toml`` file. - - -.. admonition:: Warning - :class: warning - - This is not recommended. Please consider specifying the Python package metadata. diff --git a/pyproject.toml b/pyproject.toml index 1041aa1d9..62b243b35 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,6 +52,8 @@ docs = [ 'furo>=2021.08.31', 'sphinx~=4.0', 'sphinx-autodoc-typehints>=1.10', + 'sphinx-copybutton>=0.5.0', + 'sphinx-design>=0.1.0', 'sphinx-autobuild', ]