docs: Add readthedocs examples (#1423)

Co-authored-by: Ruben Arts <[email protected]>

examples/README.md

@@ -1,18 +1,31 @@
 # Examples
 
-These examples demonstrate the main features of `pixi`. To run an example move to the folder and run `pixi run start`
-This will start the main application of the project. Some projects have more run commands available for that check the `pixi.toml`
+These examples demonstrate the main features of `pixi`. To run an example move
+to the folder and run:
 
-NOTE: Make sure your on the latest version or the version of pixi on which you are trying the examples.
+```bash
+pixi run start
+```
+
+This will start the main application of the project. Some projects have more run
+commands available:
+
+```bash
+pixi task list
+```
+
+> [!IMPORTANT]
+>
+> Make sure you are on the latest version of `pixi` to try the examples.
 
 ## Examples in other Repositories
 
 These are examples that are hosted in other repositories that use pixi for building and running the project.
 
 ### AI
 
-[Llama.cpp](https://github.com/tdejager/llama.cpp)
+- [Llama.cpp](https://github.com/tdejager/llama.cpp)
 
 ### Games
 
-[Crispy Doom](https://github.com/baszalmstra/pixi-crispy-doom)
+- [Crispy Doom](https://github.com/baszalmstra/pixi-crispy-doom)

examples/readthedocs-extend/.gitignore

@@ -0,0 +1 @@
+build/

examples/readthedocs-extend/README.md

@@ -0,0 +1,24 @@
+# ReadTheDocs: Extend Build
+
+This example shows how to [extend] a [ReadTheDocs] `sphinx` build by customizing:
+- `docs/.readthedocs.yaml` to:
+  - install native `apt` packages to support a heavyweight dependency
+  - bootstrap a [conda.environment] with the supported `mambaforge`
+  - prepare a `pixi` environment with [build.jobs]
+  - avoid another file in the project root
+    - this requires manual configuration in the ReadTheDocs web UI
+- `docs/conf.py` to:
+  - support extended ReadTheDocs features provided by [readthedocs-sphinx-ext]
+  - allow the default build to run against an un-published `rtd.rst`
+  - use `sphinx` lifecycle events to run the actual build with `pixi` tasks
+
+> [!NOTE]
+>
+> For a simpler `mkdocs` build, see the [`readthedocs-override`][override] example.
+
+[ReadTheDocs]: https://readthdocs.com
+[extend]: https://docs.readthedocs.io/en/stable/build-customization.html#extend-the-build-process
+[build.jobs]: https://docs.readthedocs.io/en/stable/config-file/v2.html#build-jobs
+[readthedocs-sphinx-ext]: https://github.com/readthedocs/readthedocs-sphinx-ext
+[conda.environment]: https://docs.readthedocs.io/en/stable/config-file/v2.html#conda-environment
+[override]: ../readthedocs-override/README.md

examples/readthedocs-extend/docs/.readthedocs.yaml

@@ -0,0 +1,30 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  apt_packages:
+    - libasound2
+    - libatk1.0-0
+    - libcups2
+    - libdbus-glib-1-2
+    - libgtk-3-0
+    - libnss3
+    - libpangocairo-1.0-0
+    - libx11-xcb1
+    - libxcomposite1
+    - libxcursor1
+    - libxdamage1
+    - libxi6
+    - libxrandr2
+    - libxss1
+    - libxtst6
+  tools:
+    python: mambaforge-latest
+  jobs:
+    pre_build:
+      - pixi install --environment=rtd
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+conda:
+  environment: docs/environment.yml

examples/readthedocs-extend/docs/conf.py

@@ -0,0 +1,25 @@
+import os
+import subprocess
+
+RTD = "READTHEDOCS"
+
+if os.getenv(RTD) == "True":
+    root_doc = "rtd"
+
+    def setup(app) -> None:
+        """Customize the sphinx build lifecycle."""
+
+        def _run_pixi(*_args) -> None:
+            args = ["pixi", "run", "-e", "rtd", "rtd"]
+            env = {k: v for k, v in os.environ.items() if k != RTD}
+            subprocess.check_call(args, env=env)
+
+        app.connect("build-finished", _run_pixi)
+else:
+    # exclude RTD
+    exclude_patterns = ["rtd.rst"]
+
+    # the "real" configuration goes here...
+    extensions = ["myst_parser"]
+
+# ... RTD will add additional configuration here

examples/readthedocs-extend/docs/environment.yml

@@ -0,0 +1,6 @@
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - pixi
+  - pip

examples/readthedocs-extend/docs/index.md

@@ -0,0 +1 @@
+# ``pixi`` on ReadTheDocs

examples/readthedocs-extend/docs/rtd.rst

@@ -0,0 +1,4 @@
+RTD
+===
+
+This is provided for the default ReadTheDocs build, and is not published.

examples/readthedocs-extend/pixi.toml

@@ -0,0 +1,38 @@
+[project]
+name = "readthedocs-extend"
+platforms = ["linux-64", "osx-64", "win-64", "osx-arm64"]
+channels = ["conda-forge"]
+
+[environments]
+rtd = ["docs", "rtd"]
+docs = ["docs", "dev"]
+
+[feature.dev.tasks.start]
+cmd = "sphinx-autobuild docs ./build/docs"
+
+[feature.docs.tasks.docs]
+cmd = "sphinx-build -W --keep-going --color -b html docs ./build/docs"
+inputs = ["docs/"]
+outputs = ["build/docs/.buildinfo"]
+
+[feature.docs.dependencies]
+firefox = "115.*"
+myst-parser = "*"
+sphinx = "*"
+
+[feature.dev.dependencies]
+sphinx-autobuild = "*"
+
+[feature.rtd.tasks.rtd]
+cmd = """
+  rm -rf $READTHEDOCS_OUTPUT/html
+  && cp -r build/docs $READTHEDOCS_OUTPUT/html
+"""
+depends-on = ["docs"]
+inputs = ["build/docs/"]
+
+
+[feature.rtd]
+platforms = ["linux-64"]
+dependencies = {requests = "*", jinja2 = ">=2.9", packaging = "*"}
+pypi-dependencies = {readthedocs-sphinx-ext = "*"}

examples/readthedocs-override/.readthedocs.yaml

@@ -0,0 +1,11 @@
+\version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    # this ensures a viable `mamba` is on `$PATH``
+    python: mambaforge-latest
+  commands:
+    - mamba install -c conda-forge -c nodefaults pixi
+    - pixi install
+    - pixi run docs
+    - pixi run readthedocs

examples/readthedocs-override/README.md

@@ -0,0 +1,17 @@
+# ReadTheDocs: Override Build
+
+> [!WARNING]
+> The full build override feature is still in _beta_. See the ReadTheDocs
+> [documentation][override] for more.
+
+This example shows how to [override] a [ReadTheDocs] `mkdocs` build by using
+`pixi` in [build.commands].
+
+> [!NOTE]
+>
+> For a more involved `sphinx` build, see the [`readthedocs-extend`][extend] example.
+
+[ReadTheDocs]: https://readthdocs.com
+[override]: https://docs.readthedocs.io/en/stable/build-customization.html#override-the-build-process
+[build.commands]: https://docs.readthedocs.io/en/stable/config-file/v2.html#build-commands
+[extend]: ../readthedocs-extend/README.md

examples/readthedocs-override/docs/index.md

@@ -0,0 +1 @@
+# `pixi` on ReadTheDocs

examples/readthedocs-override/mkdocs.yml

@@ -0,0 +1,3 @@
+site_name: basic example
+nav:
+  - README: index.md