Add Sphinx documentation (#34)

* Local docs builds with tox
* GitHub Pages publishing with the Sphinx recommended actions
* Project overview page
* Initial developer guide
* Initial (very rough) Python API docs
* Glossary of key terms
* Initial design discussion page

.github/workflows/docs.yml

@@ -0,0 +1,77 @@
+name: "Sphinx: Render docs"
+
+on:
+  pull_request:
+    branches:
+      - "**"
+    paths:
+      # Run for changes to *this* workflow file, but not for other workflows
+      - ".github/workflows/docs.yml"
+      # Trigger off docs and Python source code changes
+      - "docs/**"
+      - "src/**.py"
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Not actually a matrix build, but defined as one for consistency
+      max-parallel: 1
+      matrix:
+        python-version: [3.12]
+        os: [ubuntu-latest]
+    permissions:
+      # Allow updating the gh-pages branch
+      contents: write
+
+    # Check https://github.com/actions/action-versions/tree/main/config/actions
+    # for latest versions if the standard actions start emitting warnings
+    steps:
+    - uses: actions/checkout@v4
+
+    # sphinx-action uses docker under the hood and doesn't play nice with the
+    # dependency caching, so it may be better to switch to using `tox -e docs`
+    # and living without the nice integrated GitHub Actions error reporting.
+
+    # - name: Set up Python ${{ matrix.python-version }}
+    #   uses: actions/setup-python@v5
+    #   with:
+    #     python-version: ${{ matrix.python-version }}
+
+    # - name: Get pip cache dir
+    #   id: pip-cache
+    #   run: |
+    #     echo "dir=$(python -m pip cache dir)" >> $GITHUB_OUTPUT
+
+    # - name: Cache docs build dependencies
+    #   uses: actions/cache@v4
+    #   with:
+    #     path: ${{ steps.pip-cache.outputs.dir }}
+    #     key:
+    #       pip-docs-${{ matrix.os }}-${{ matrix.python-version }}-v1-${{ hashFiles('docs/requirements.txt') }}
+    #     restore-keys: |
+    #       pip-docs-${{ matrix.os }}-${{ matrix.python-version }}-v1-
+
+    - name: Build HTML
+      uses: ammaraskar/[email protected]
+      with:
+        docs-folder: "docs/"
+        # Skip link check until after the venvstacks repo is public
+        # pre-build-command: "sphinx-build -b linkcheck . _build"
+        build-command: "sphinx-build -b dirhtml . _build"
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: docs/_build/
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/_build/

README.md

@@ -67,6 +67,8 @@ Caveats and Limitations
   declared as stable in the documentation may be renamed or relocated without a
   deprecation period. API stabilisation (mostly splitting up the overly large
   `venvstacks.stacks` namespace) will be the trigger for the 1.0 milestone release.
+* while the `venvstacks` CLI is broadly stable, there are still some specific areas
+  where changes may occur (such as in the handling of relative paths).
 * dynamic library dependencies across layers currently only work on Windows.
   There is a [proposal](https://github.com/lmstudio-ai/venvstacks/issues/1) in
   place for resolving that limitation, but it has not yet been implemented.

ci-bootstrap-requirements.txt

@@ -19,9 +19,9 @@ distlib==0.3.9 \
 filelock==3.16.1 \
     --hash=sha256:2082e5703d51fbf98ea75855d9d5527e33d8ff23099bec374a134febee6946b0 \
     --hash=sha256:c249fbfcd5db47e5e2d6d62198e565475ee65e4831e2561c8e313fa7eb961435
-findpython==0.6.1 \
-    --hash=sha256:1fb4d709205de185b0561900267dfff64a841c910fe28d6038b2394ff925a81a \
-    --hash=sha256:56e52b409a92bcbd495cf981c85acf137f3b3e51cc769b46eba219bb1ab7533c
+findpython==0.6.2 \
+    --hash=sha256:bda62477f858ea623ef2269f5e734469a018104a5f6c0fd9317ba238464ddb76 \
+    --hash=sha256:e0c75ba9f35a7f9bb4423eb31bd17358cccf15761b6837317719177aeff46723
 h11==0.14.0 \
     --hash=sha256:8f19fbbe99e72420ff35c00b27a34cb9937e902a8b810e2c88300c6f0a3b699d \
     --hash=sha256:e3fe4ac4b851c468cc8363d500db52c2ead036020723024a109d37346efaa761
@@ -69,9 +69,9 @@ packaging==24.1 \
 pbs-installer==2024.10.10 \
     --hash=sha256:228bba8e78134c407ee6637da6a5a16479aaa702332bfb1b95d873fc00802305 \
     --hash=sha256:b82fb5c96a4ca2a8c2ea2521268fa83fa18c1bfa32decfb3d77139a07c13f90c
-pdm==2.19.2 \
-    --hash=sha256:42af4e0897b139656e003767e99c4f77014bf36d9a7b759d3e09b49ee5979143 \
-    --hash=sha256:efb39264569181d0375536ef81c556648f16b540d429a53715730490a2283567
+pdm==2.19.3 \
+    --hash=sha256:80594e5d6167fb17ea724df09b68cdfe9c601ad7f218f1beea2c032b61bf30e9 \
+    --hash=sha256:a9cc7f2078cd3b25ac645ffb5eca9d6b3d5dfcd788eaddfb6083432da71c97c2
 platformdirs==4.3.6 \
     --hash=sha256:357fb2acbc885b0419afd3ce3ed34564c13c9b95c89360cd9563f73aa5e2b907 \
     --hash=sha256:73e575e1408ab8103900836b97580d5307456908a03e92031bab39e4554cc3fb
@@ -111,6 +111,6 @@ typing-extensions==4.12.2 \
 unearth==0.17.2 \
     --hash=sha256:0b8a2afd3476f1ab6155fc579501ac47fffe43547d88a70e5a5b76a7fe6caa2c \
     --hash=sha256:4d21af1238a583835fca156322f7225382e718cdcc42d6278050a88e605c4ad5
-virtualenv==20.26.6 \
-    --hash=sha256:280aede09a2a5c317e409a00102e7077c6432c5a38f0ef938e643805a7ad2c48 \
-    --hash=sha256:7345cc5b25405607a624d8418154577459c3e0277f5466dd79c49d5e492995f2
+virtualenv==20.27.0 \
+    --hash=sha256:2ca56a68ed615b8fe4326d11a0dca5dfbe8fd68510fb6c6349163bed3c15f2b2 \
+    --hash=sha256:44a72c29cceb0ee08f300b314848c86e57bf8d1f13107a5e671fb9274138d655