Add Sphinx documentation

* Local docs builds with tox * GitHub Pages publishing with the Sphinx recommended actions * Initial developer guide * Initial (very rough) Python API docs * Glossary of key terms * Placeholder page for the project overview
lmstudio-ai · Oct 21, 2024 · b4b2602 · b4b2602
1 parent cfd0401
commit b4b2602
Show file tree

Hide file tree

Showing 57 changed files with 1,957 additions and 142 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,48 @@
+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: 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
+
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+      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/dirhtml/
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/_build/dirhtml
diff --git a/ci-bootstrap-requirements.txt b/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
diff --git a/ci-constraints.txt b/ci-constraints.txt
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,19 @@
+Python API
+==========
+
+.. warning::
+
+   The Python API is *NOT YET STABLE*.
+   Function, class, and method names may change between releases
+   without any deprecation period.
+
+.. automodule:: venvstacks
+
+   .. rubric:: Modules
+
+   .. autosummary::
+      :toctree:
+
+      cli
+      pack_venv
+      stacks
diff --git a/docs/api/venvstacks.cli.main.rst b/docs/api/venvstacks.cli.main.rst
@@ -0,0 +1,6 @@
+venvstacks.cli.main
+===================
+
+.. currentmodule:: venvstacks.cli
+
+.. autofunction:: main
diff --git a/docs/api/venvstacks.cli.rst b/docs/api/venvstacks.cli.rst
@@ -0,0 +1,12 @@
+venvstacks.cli
+==============
+
+.. automodule:: venvstacks.cli
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+
+      main
diff --git a/docs/api/venvstacks.pack_venv.convert_symlinks.rst b/docs/api/venvstacks.pack_venv.convert_symlinks.rst
@@ -0,0 +1,6 @@
+venvstacks.pack\_venv.convert\_symlinks
+=======================================
+
+.. currentmodule:: venvstacks.pack_venv
+
+.. autofunction:: convert_symlinks
diff --git a/docs/api/venvstacks.pack_venv.create_archive.rst b/docs/api/venvstacks.pack_venv.create_archive.rst
@@ -0,0 +1,6 @@
+venvstacks.pack\_venv.create\_archive
+=====================================
+
+.. currentmodule:: venvstacks.pack_venv
+
+.. autofunction:: create_archive
diff --git a/docs/api/venvstacks.pack_venv.export_venv.rst b/docs/api/venvstacks.pack_venv.export_venv.rst
@@ -0,0 +1,6 @@
+venvstacks.pack\_venv.export\_venv
+==================================
+
+.. currentmodule:: venvstacks.pack_venv
+
+.. autofunction:: export_venv
diff --git a/docs/api/venvstacks.pack_venv.get_archive_path.rst b/docs/api/venvstacks.pack_venv.get_archive_path.rst
@@ -0,0 +1,6 @@
+venvstacks.pack\_venv.get\_archive\_path
+========================================
+
+.. currentmodule:: venvstacks.pack_venv
+
+.. autofunction:: get_archive_path
diff --git a/docs/api/venvstacks.pack_venv.rst b/docs/api/venvstacks.pack_venv.rst
@@ -0,0 +1,15 @@
+venvstacks.pack\_venv
+=====================
+
+.. automodule:: venvstacks.pack_venv
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+
+      convert_symlinks
+      create_archive
+      export_venv
+      get_archive_path
diff --git a/docs/api/venvstacks.stacks.ApplicationEnv.rst b/docs/api/venvstacks.stacks.ApplicationEnv.rst
@@ -0,0 +1,62 @@
+venvstacks.stacks.ApplicationEnv
+================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: ApplicationEnv
+
+
+   .. automethod:: __init__
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ApplicationEnv.create_archive
+      ~ApplicationEnv.create_environment
+      ~ApplicationEnv.define_archive_build
+      ~ApplicationEnv.ensure_runtime_dependencies
+      ~ApplicationEnv.export_environment
+      ~ApplicationEnv.get_constraint_paths
+      ~ApplicationEnv.install_build_requirements
+      ~ApplicationEnv.install_requirements
+      ~ApplicationEnv.link_base_runtime_paths
+      ~ApplicationEnv.link_layered_environments
+      ~ApplicationEnv.lock_requirements
+      ~ApplicationEnv.remove_build_only_packages
+      ~ApplicationEnv.report_python_site_details
+      ~ApplicationEnv.request_export
+      ~ApplicationEnv.select_operations
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ApplicationEnv.category
+      ~ApplicationEnv.env_name
+      ~ApplicationEnv.env_spec
+      ~ApplicationEnv.install_target
+      ~ApplicationEnv.kind
+      ~ApplicationEnv.launch_module_name
+      ~ApplicationEnv.linked_constraints_paths
+      ~ApplicationEnv.linked_dynlib_paths
+      ~ApplicationEnv.linked_frameworks
+      ~ApplicationEnv.linked_pylib_paths
+      ~ApplicationEnv.want_build
+      ~ApplicationEnv.want_lock
+      ~ApplicationEnv.want_publish
+      ~ApplicationEnv.was_built
+      ~ApplicationEnv.was_created
+      ~ApplicationEnv.build_path
+      ~ApplicationEnv.requirements_path
+      ~ApplicationEnv.index_config
+      ~ApplicationEnv.env_path
+      ~ApplicationEnv.pylib_path
+      ~ApplicationEnv.dynlib_path
+      ~ApplicationEnv.executables_path
+      ~ApplicationEnv.python_path
+      ~ApplicationEnv.env_lock
+      ~ApplicationEnv.base_python_path
+      ~ApplicationEnv.tools_python_path
+      ~ApplicationEnv.py_version
+
diff --git a/docs/api/venvstacks.stacks.ApplicationSpec.rst b/docs/api/venvstacks.stacks.ApplicationSpec.rst
@@ -0,0 +1,35 @@
+venvstacks.stacks.ApplicationSpec
+=================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: ApplicationSpec
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ApplicationSpec.get_requirements_fname
+      ~ApplicationSpec.get_requirements_path
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ApplicationSpec.ENV_PREFIX
+      ~ApplicationSpec.category
+      ~ApplicationSpec.env_name
+      ~ApplicationSpec.kind
+      ~ApplicationSpec.launch_module_path
+      ~ApplicationSpec.frameworks
+      ~ApplicationSpec.runtime
+      ~ApplicationSpec.name
+      ~ApplicationSpec.versioned
+      ~ApplicationSpec.requirements
+      ~ApplicationSpec.build_requirements
+      ~ApplicationSpec.platforms
+
diff --git a/docs/api/venvstacks.stacks.ArchiveBuildMetadata.rst b/docs/api/venvstacks.stacks.ArchiveBuildMetadata.rst
@@ -0,0 +1,27 @@
+venvstacks.stacks.ArchiveBuildMetadata
+======================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: ArchiveBuildMetadata
+
+
+   .. automethod:: __init__
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ArchiveBuildMetadata.layer_name
+      ~ArchiveBuildMetadata.install_target
+      ~ArchiveBuildMetadata.requirements_hash
+      ~ArchiveBuildMetadata.lock_version
+      ~ArchiveBuildMetadata.locked_at
+      ~ArchiveBuildMetadata.runtime_name
+      ~ArchiveBuildMetadata.required_layers
+      ~ArchiveBuildMetadata.app_launch_module
+      ~ArchiveBuildMetadata.app_launch_module_hash
+      ~ArchiveBuildMetadata.archive_build
+      ~ArchiveBuildMetadata.archive_name
+      ~ArchiveBuildMetadata.target_platform
+
diff --git a/docs/api/venvstacks.stacks.ArchiveBuildRequest.rst b/docs/api/venvstacks.stacks.ArchiveBuildRequest.rst
@@ -0,0 +1,29 @@
+venvstacks.stacks.ArchiveBuildRequest
+=====================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: ArchiveBuildRequest
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ArchiveBuildRequest.create_archive
+      ~ArchiveBuildRequest.define_build
+      ~ArchiveBuildRequest.needs_archive_build
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ArchiveBuildRequest.env_name
+      ~ArchiveBuildRequest.env_lock
+      ~ArchiveBuildRequest.archive_base_path
+      ~ArchiveBuildRequest.build_metadata
+      ~ArchiveBuildRequest.needs_build
+
diff --git a/docs/api/venvstacks.stacks.ArchiveHashes.rst b/docs/api/venvstacks.stacks.ArchiveHashes.rst
@@ -0,0 +1,15 @@
+venvstacks.stacks.ArchiveHashes
+===============================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: ArchiveHashes
+
+   .. automethod:: __init__
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ArchiveHashes.sha256
+
diff --git a/docs/api/venvstacks.stacks.ArchiveMetadata.rst b/docs/api/venvstacks.stacks.ArchiveMetadata.rst
@@ -0,0 +1,28 @@
+venvstacks.stacks.ArchiveMetadata
+=================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: ArchiveMetadata
+
+   .. automethod:: __init__
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ArchiveMetadata.layer_name
+      ~ArchiveMetadata.install_target
+      ~ArchiveMetadata.requirements_hash
+      ~ArchiveMetadata.lock_version
+      ~ArchiveMetadata.locked_at
+      ~ArchiveMetadata.runtime_name
+      ~ArchiveMetadata.required_layers
+      ~ArchiveMetadata.app_launch_module
+      ~ArchiveMetadata.app_launch_module_hash
+      ~ArchiveMetadata.archive_build
+      ~ArchiveMetadata.archive_name
+      ~ArchiveMetadata.target_platform
+      ~ArchiveMetadata.archive_size
+      ~ArchiveMetadata.archive_hashes
+