mesonbuild · FFY00 · Feb 1, 2023 · Jan 27, 2023 · Jan 27, 2023 · Jan 27, 2023
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -23,5 +23,5 @@ jobs:
         with:
           python-version: '3.11'
       - uses: actions/checkout@v3
-      - run: python -m pip install .[docs]
-      - run: python -m sphinx -W -b html docs/ build/html/
+      - run: python -m pip install nox
+      - run: nox -s docs
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,9 +2,10 @@
 ..
 .. SPDX-License-Identifier: MIT
 
-+++++++++
-Changelog
-+++++++++
+
+++++++++++
+Change-log
+++++++++++
 
 
 0.13.0.pre0 (30-01-2023)
@@ -87,7 +88,7 @@ Changelog
 0.6.0 (21-06-2022)
 ==================
 
-- Project relicensed to MIT
+- Project re-licensed to MIT
 - Error out when running in an unsupported interpreter
 - Fix slightly broken Debian heuristics
 - Update ``pep621`` dependency to ``pyproject-metadata``
@@ -110,7 +111,7 @@ Changelog
 ==================
 
 - Initial cross-platform support
-  - Bundling libraries stioll is only supported on Linux
+  - Bundling libraries is still only supported on Linux
 - Add initial documentation
 - The build directory is now located in the project source
 
@@ -138,7 +139,7 @@ Changelog
 0.1.1 (28-10-2021)
 ==================
 
-- Fix minor compability issue with Python < 3.9
+- Fix minor compatibility issue with Python < 3.9
 
 
 0.1.0 (28-10-2021)

diff --git 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
@@ -37,7 +37,13 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
     'sphinx_autodoc_typehints',
+    'sphinx_contributors',
+    'sphinx_copybutton',
+    'sphinx_design',
+    'sphinxcontrib.spelling',
+    'sphinxext.opengraph',
 ]
 
 intersphinx_mapping = {
@@ -55,6 +61,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 +71,33 @@
 html_theme = 'furo'
 html_title = f'meson-python {version}'
 
+html_static_path = ['static']
+html_css_files = [
+    'css/contributors.css',
+]
+
+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'
+        ),
+    },
+}
+
+
+# Spellchecking
+
+spelling_show_suggestions = True
+spelling_warning = True
+
+
+# Open Graph
+
+ogp_site_url = 'https://meson-python.readthedocs.io'
+ogp_site_name = 'meson-python documentation'
+
+
 # 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,25 @@
+.. 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 we don't support ``install_data``
+
+     - Link to the relevant :ref:`reference-limitations` section
+
+   - ?
+
+
+You can find the old documentation :ref:`here <explanations-design-old>`.
diff --git a/docs/explanations/editable-installs.rst 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
@@ -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``