Skip to content

Commit

Permalink
DOC: clean up front page and intro tutorial, state files must be in VCS
Browse files Browse the repository at this point in the history 
Closes gh-420
  • Loading branch information
@rgommers @dnicolodi
rgommers authored and dnicolodi committed Sep 2, 2023
1 parent a331ed0 commit 4f1874f
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 87 deletions.
18 changes: 3 additions & 15 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ meson-python

.. highlights::

``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.
``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.


Want to look at examples in real projects? Check out our curated list of
Expand All @@ -20,19 +20,12 @@ Want to look at examples in real projects? Check out our curated list of
Where to start?
===============


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.


Experienced users
-----------------

If you are already familiarized with Python packaging, we recommend you check
If you are already familiar 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.

Expand All @@ -55,10 +48,6 @@ free to open an issue on our bugtracker_.
`discussion page`_ first.


In addition, the `#meson-python`_ channel on the `PyPA Discord`_ may be useful
for quick questions - one ``meson-python`` maintainer is active there.


.. toctree::
:caption: Tutorials
:hidden:
Expand Down Expand Up @@ -117,7 +106,6 @@ for quick questions - one ``meson-python`` maintainer is active there.
Issue Tracker <https://github.com/mesonbuild/meson-python/issues>


.. _Meson: https://github.com/mesonbuild/meson
.. _getting started: usage/start.html
.. _pip: https://github.com/pypa/pip
.. _pypa/build: https://github.com/pypa/build
Expand Down
109 changes: 37 additions & 72 deletions docs/tutorials/introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ 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
=======================
Creating 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.
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
Expand Down Expand Up @@ -87,8 +87,7 @@ we want it to build, and how to do it.
project('purelib-and-platlib', 'c')
py_mod = import('python')
py = py_mod.find_installation(pure: false)
py = import('python').find_installation(pure: false)
py.extension_module(
'our_first_module',
Expand All @@ -97,16 +96,16 @@ we want it to build, and how to do it.
)
Here, we use the `Meson Python module`_ to build our ``our_first_module``
Here, we use Meson's `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.


Configure our Python package
============================
Configuring our Python package
==============================

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
Expand All @@ -115,12 +114,10 @@ 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
backend should be used for the project - set it to ``'mesonpy'`` to use
``meson-python``. ``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``.

other dependencies you might need (e.g., ``Cython``).

.. code-block:: toml
:caption: pyproject.toml
Expand All @@ -129,11 +126,9 @@ other dependencies you might need (eg. ``Cython``), in our case it's just
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.

self-explanatory:

.. code-block:: toml
:caption: pyproject.toml
Expand All @@ -151,35 +146,20 @@ self-explanatory by looking at our example.
{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 `toml.io <https://toml.io>`_.
Our example doesn't make use of all the fields available in the ``[project]``
section. Check out the `PyPA documentation on project metadata`_ for more
examples and details.


Testing the project
-------------------

Now we should have a valid Python project, let's test it.

We will install it with pip_
Now we should have a valid Python project, so let's test it.

We will install it with pip_:

.. code-block:: console
Expand Down Expand Up @@ -214,23 +194,22 @@ 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*
-------------------------------------------

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 file-system.
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 file system.

If your project uses Python extension modules, your *wheels* will be specific to
If your project uses Python extension modules, your wheels will be specific to
both the platform and the Python version [#stable-abi]_.

While distributing *wheels* is not mandatory, they make the
While distributing wheels is not mandatory, 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.
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 process.


.. [#pure-wheels]
Expand All @@ -249,32 +228,26 @@ dependencies and going through the likely expensive build.
Building the project
--------------------

Before continuing, ensure you have committed the three files we created so far
to your Git repository - ``meson-python`` will only take into account the files
that Git knows about.

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 <https://pypa-build.readthedocs.io/>`__.


.. admonition:: Building wheels for multiple platforms
:class: tip

If our project only contains pure-Python (``.py``) code, the *wheel* we just
built will work on all platforms, as it is a *pure* wheel, but if the
If our project only contains pure-Python (``.py``) code, the wheel we just
built will work on all platforms, as it is a pure wheel, but if the
project contains native code, it will be specific for our machine's platform.

When releasing, you'll usually want to build for at least most of the other
Expand Down Expand Up @@ -314,14 +287,6 @@ For this, we will use Twine_.
You can find more about how to use the `Test PyPI`_ in
`its PyPA documentation page <https://packaging.python.org/en/latest/guides/using-testpypi/>`_.


.. admonition:: Check the twine documentation
:class: seealso

To learn more about Twine_, you can check
`their documentation <https://twine.readthedocs.io/>`__.


After this, your package should be available on PyPI_, and installable with
pip_.

Expand All @@ -332,8 +297,8 @@ pip_.
.. _Meson: https://github.com/mesonbuild/meson
.. _Meson Python module: https://mesonbuild.com/Python-module.html
.. _Meson: https://mesonbuild.com/
.. _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/
Expand Down

0 comments on commit 4f1874f

Please sign in to comment.