DOC: clean up front page and intro tutorial, state files must be in VCS

Closes gh-420

Author: rgommers

docs/index.rst

@@ -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
@@ -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.
 
@@ -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:
@@ -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

docs/tutorials/introduction.rst

@@ -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
@@ -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',
@@ -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
@@ -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
@@ -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
@@ -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
 
@@ -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]
@@ -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
@@ -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_.
 
@@ -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/