Add necessary stuff for deploying an mkdocs site (#25)

* Add necessary stuff for deploying an mkdocs site
* Use commit hashes for security
* Address feedback; do not duplicate README
* Rework structure of the site

- Move index.html content into different pages
- Write more of an intro in index.html (moved some README content)
- Add initial status tracker

* remove vestigal pyenv/README.md
* Expand stubs in porting guide
* Tweaks to CI page
* Tweaks to the "porting extension modules" page
* Tweaks to "Running with the GIL disabled" page
* Extend the Installing page with binary install options
* Improve and extend the tracking table

Organized alphabetically (more scalable), and using the lessons from the NumPy
2.0 rollout tracker for added columns.

* Extend table to all currently tracked packages on issue tracker
* Reorder table, nightlies at the end. Add CMake

Not relevant for all packages, and importance of nightlies should fade away
over time.

* Rewrite the front page of the site
* Add some front matter to the compatibility tracking page
* Update link in README
* Add joblib to tracker
* Update deploy job to deploy to py-free-threading.github.io repo

---------

Co-authored-by: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>

.github/workflows/deploy.yml

@@ -0,0 +1,52 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '.github/worksflows/deploy.yml'
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements.txt'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '.github/worksflows/deploy.yml'
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements.txt'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
+        with:
+          python-version: 3.12
+
+      - name: Install MkDocs & co
+        run: pip install -r requirements.txt
+
+      - name: Build site
+        run: mkdocs build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        with:
+          personal_token: ${{ secrets.PYFREETHREADING_DEPLOY_KEY }}
+          external_repository: py-free-threading/py-free-threading.github.io
+          publish_dir: ./site
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

docs/ci.md

@@ -0,0 +1,68 @@
+# Setting up CI
+
+Currently the `setup-python` GitHub Action [does not
+support](https://github.com/actions/setup-python/issues/771) installing a
+free-threaded build. For now, the easiest way to get a free-threaded Python
+build on a CI runner is with the `deadsnakes` Ubuntu PPA and the
+`deadsnakes-action` GitHub Action:
+
+```yaml
+jobs:
+  free-threaded:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@...
+    - uses: deadsnakes/action@...
+      with:
+          python-version: '3.13.0b2'
+          nogil: true
+```
+
+You should replace the ellipses with versions for the actions. If there is a
+newer CPython 3.13 release available since this document was written or
+updated, use that version instead.
+
+[cibuildwheel](https://cibuildwheel.pypa.io/en/stable/) has support
+for building free-threaded wheels on all platforms. If your project releases
+nightly wheels, we suggest configuring `cibuildwheel` to build nightly
+free-threaded wheels.
+
+You will need to specify the following variables in the environment for the
+cibuildwheel action:
+
+```yaml
+      - name: Build wheels
+        uses: pypa/cibuildwheel@...
+        env:
+          CIBW_PRERELEASE_PYTHONS: True
+          CIBW_FREE_THREADED_SUPPORT: True
+          CIBW_BUILD: cp313t-${{ matrix.buildplat }}
+          # TODO: remove along with installing build deps in
+          # cibw_before_build.sh when a released cython can build numpy
+          CIBW_BUILD_FRONTEND: "pip; args: --no-build-isolation"
+```
+
+As above, replace the ellipses with a `cibuildwheel` version.
+
+If your project depends on Cython, you will need to install a Cython nightly
+wheel in the build, as the newest stable release of Cython cannot generate code
+that will compile under the free-threaded build. You likely do not need to
+disable `pip`'s build isolation if your project does not depend on Cython.
+
+You can install nightly wheels for Cython and NumPy using the following
+install command:
+
+```
+pip install -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple cython numpy
+```
+
+Note that nightly wheels may not be available on all platforms yet. Windows
+wheels, in particular, are not currently available for NumPy or projects that
+depend on NumPy (e.g., SciPy).
+
+You will also likely need to manually pass `-Xgil=0` or set `PYTHON_GIL=0` in
+your shell environment while running tests to ensure the GIL is actually
+disabled during tests, at least until you can register that your extension
+modules support disabling the GIL via `Py_mod_gil` and all of your runtime test
+dependencies do the same. It is not currently possible to mark that a Cython
+module supports running without the GIL.

docs/index.md

@@ -0,0 +1,45 @@
+---
+description: py-free-threading is a centralized collection of documentation and trackers around compatibility with free-threaded CPython for the Python open source ecosystem
+---
+
+# Introduction
+
+Free-threaded CPython is coming! :material-language-python: :thread:
+
+After the [acceptance by the Python Steering Council](https://discuss.python.org/t/a-steering-council-notice-about-pep-703-making-the-global-interpreter-lock-optional-in-cpython/30474)
+of, and the [gradual rollout strategy](https://discuss.python.org/t/pep-703-making-the-global-interpreter-lock-optional-in-cpython-acceptance/37075) for,
+[PEP 703 - Making the Global Interpreter Lock Optional in CPython](https://peps.python.org/pep-0703/),
+a lot of work is happening both in CPython itself and across the Python ecosystem.
+
+This website aims to serve as a centralized resource both for Python package
+maintainers and end users interested in supporting or experimenting with
+free-threaded Python. An overview of the compatibility status of various Python
+libraries is maintained in:
+
+- [Compatibility status tracking](tracking.md)
+
+This website also provide documentation and porting guidance - with a focus on
+extension modules using the Python C API, because that's where most of the work
+will be. The following resources should get you started:
+
+- [Installing free-threaded CPython](installing_cpython.md)
+- [Running Python with the GIL disabled](running-gil-disabled.md)
+- [Porting extension modules to support free-threading](porting.md)
+- [Setting up CI](ci.md)
+
+
+
+## About this site
+
+Any contributions are very much welcome - please open issues or pull requests
+[on this repo](https://github.com/Quansight-Labs/free-threaded-compatibility)
+for anything that seems in scope for this site or for tracking issues related
+to support for free-threaded Python across the ecosystem.
+
+This site is maintained primarily by Quansight Labs, where a team is working
+together with the Python runtime team at Meta and stakeholders across the
+ecosystem to jumpstart work on converting the libraries that make up the
+scientific Python and AI/ML stacks to work with the free-threaded build of
+CPython 3.13. Additionally, that effort will look at libraries like PyO3 that
+are needed to interface with CPython from other languages.
+

docs/installing_cpython.md

@@ -0,0 +1,84 @@
+# Installing a free-threaded Python
+
+To install a free-threaded CPython interpreter, you can either use a pre-built
+binary or build CPython from source. The former is quickest to get started
+with. Building from source is not too difficult either though, and in case you
+hit a bug that may involve CPython itself then you may want to build from
+source.
+
+
+## Binary install options
+
+There are a growing number of options to install a free-threaded interpreter,
+from the python.org installers to Linux distro and Conda package managers.
+
+!!! note
+
+    For any of these options, please check after the install succeeds that you
+    have a `pip` version that is recent enough (`>=24.1`), and upgrade it if
+    that isn't the case. Older `pip` versions will select wheels with the
+    `cp313` tag (binary-incompatible) rather than the `cp313t` tag.
+
+
+### python.org installers
+
+The [python.org downloads page](https://www.python.org/download/pre-releases/)
+provides macOS and Windows installers that have experimental support. Note
+that you have to customize the install - e.g., for Windows there is a
+_Download free-threaded binaries_ checkbox under "Advanced Options".
+See also the [Using Python on Windows](https://docs.python.org/3.13/using/windows.html#installing-free-threaded-binaries)
+section of the Python 3.13 docs.
+
+
+### Linux distros
+
+=== "Fedora"
+
+    Fedora ships a packaged version, which you can install with:
+    ```
+    sudo dnf install python3.13-freethreading
+    ```
+    This will install the interpreter at `/usr/bin/python3.13t`.
+
+=== "Ubuntu"
+
+    For Ubuntu you can use the [deadsnakes PPA](https://launchpad.net/%7Edeadsnakes/+archive/ubuntu/ppa/+packages)
+    by adding it to your repositories and then installing `python3.13-nogil`:
+    ```
+    sudo add-apt-repository ppa:deadsnakes
+    sudo apt-get update
+    sudo apt-get install python3.13-nogil
+    ```
+
+
+### Conda
+
+Conda packages are currently available for macOS arm64 and Linux x86-64 under a
+label in the `ad-testing` (`ad` means "anaconda distribution") channel:
+
+```
+conda create -n nogil -c defaults -c ad-testing/label/py313_nogil python=3.13
+```
+
+
+## Building from source
+
+Currently we suggest building CPython from source using the latest version of
+the CPython `main` branch. See
+[the build instructions](https://devguide.python.org/getting-started/setup-building/index.html)
+in the CPython developer guide. You will need to install [needed third-party
+dependencies](https://devguide.python.org/getting-started/setup-building/index.html#install-dependencies)
+before building. To build the free-threaded version of CPython, pass
+`--disable-gil` to the `configure` script:
+
+```bash
+./configure --with-pydebug --disable-gil
+```
+
+If you will be switching Python versions often, it may make sense to
+build CPython using [pyenv](https://github.com/pyenv/pyenv). In order to
+do that, you can use the following:
+
+```bash
+pyenv install --debug 3.13t-dev
+```