From 8dcbba81f3edcd3fbc76df288570984301e5ee97 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Wed, 30 Oct 2024 23:45:53 +1000 Subject: [PATCH] Post-rc1 docs and metadata updates (#59) --- CHANGELOG.rst | 2 +- README.md | 56 ++++++++++--------- ...34_ncoghlan_fix_prepublication_details.rst | 11 ++++ docs/glossary.rst | 2 +- docs/index.rst | 41 ++++++++++++-- docs/overview.rst | 46 +++------------ pyproject.toml | 8 ++- 7 files changed, 93 insertions(+), 73 deletions(-) create mode 100644 changelog.d/20241030_224034_ncoghlan_fix_prepublication_details.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f08ce6e..e180101 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -9,7 +9,7 @@ Changelog Until the Python API has stabilised, ``venvstacks`` is using `ZeroVer `__ (starting from 0.1.0). - Refer to the :ref:`version-numbering` for additional details + Refer to :ref:`version-numbering` for additional details on the way releases are versioned. diff --git a/README.md b/README.md index dd9df93..879f969 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -Layered Virtual Environment Stacks for Python -============================================= +Virtual Environment Stacks for Python +===================================== The `venvstacks` project uses Python's `sitecustomize.py` environment setup feature to chain together three layers of Python virtual environments: @@ -11,29 +11,26 @@ chain together three layers of Python virtual environments: Application layer environments may include additional unpackaged Python launch modules or packages for invocation with `python`'s `-m` switch. -This project does NOT support combining arbitrary virtual environments with each other. -Instead, it allows larger integrated applications to split up their Python dependencies into -distinct layers, without needing to download and install multiple copies of large -dependencies (such as the `pytorch` ML/AI framework). The environment stack specification -and build process helps ensure that shared dependencies are kept consistent across layers, -while unshared dependencies are free to vary across the application components that need them. +While the layers are archived and published separately, their dependency locking is integrated, +allowing the application layers to share dependencies installed in the framework layers, +and the framework layers to share dependencies installed in the runtime layers. -As an example, the main sample project used in the test suite defines the following layers: +Refer to the [Project Overview](https://lmstudio-ai.github.io/venvstacks/overview/) for an +example of specifying, locking, building, and publishing a set of environment stacks. -* `cpython@3.11`: CPython 3.11 base runtime -* `cpython@3.12`: CPython 3.12 base runtime -* `framework-scipy`: example framework layer (based on 3.11 runtime) -* `framework-sklearn` example framework layer (based on 3.12 runtime) -* `framework-http-client`: example framework layer (based on 3.11 runtime) -* `app-scipy-import`: example app layer with a single framework and a simple launch module -* `app-scipy-client`: example app layer with two frameworks and a multi-file launch package -* `app-sklearn-import`: example of defining a platform specific app layer -Refer to `tests\sample_project\venvstacks.toml` for the full definition of this example. +Installing +---------- -To avoid relying on the Python ecosystem's still limited support for cross-platform -component installation, the stack build processes need to be executed on the target -platform (for example, by using an OS matrix in GitHub Actions). +`venvstacks` is available from the [Python Package Index](https://pypi.org/project/venvstacks/), +and can be installed with [pipx](https://pypi.org/project/pipx/): + + $ pipx install venvstacks + +Alternatively, it can be installed as a user level package (although this may +make future Python version upgrades more irritating): + + $ pip install --user venvstacks Interactions with other packaging tools @@ -63,18 +60,27 @@ may be useful in generating the required input archives. Caveats and Limitations ----------------------- -* the `venvstacks` Python API is *not yet stable*. Any interface not specifically +* This project does NOT support combining arbitrary virtual environments with each other. + Instead, it allows larger integrated applications to split up their Python dependencies into + distinct layers, without needing to download and install multiple copies of large + dependencies (such as the `pytorch` ML/AI framework). The environment stack specification + and build process helps ensure that shared dependencies are kept consistent across layers, + while unshared dependencies are free to vary across the application components that need them. +* The `venvstacks` Python API is *not yet stable*. Any interface not specifically 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 +* 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. +* Dynamic library dependencies across layers currently only work on Windows. There is a [proposal](https://github.com/lmstudio-ai/venvstacks/issues38) in place for resolving that limitation, but it has not yet been implemented. -* local exports to filesystems which do not support symlinks (such as `VFAT` and +* Local exports to filesystems which do not support symlinks (such as `VFAT` and `FAT32`) are nominally supported (with symlinks being replaced by the files they refer to), but this support is *not* currently tested. +* To avoid relying on the Python ecosystem's still limited support for cross-platform + component installation, the stack build processes need to be executed on the target + platform (for example, by using an OS matrix in GitHub Actions). Project History diff --git a/changelog.d/20241030_224034_ncoghlan_fix_prepublication_details.rst b/changelog.d/20241030_224034_ncoghlan_fix_prepublication_details.rst new file mode 100644 index 0000000..eb88818 --- /dev/null +++ b/changelog.d/20241030_224034_ncoghlan_fix_prepublication_details.rst @@ -0,0 +1,11 @@ +Changed +------- + +- Included project URLs in project metadata + +- Added installation instructions to README.md + +- Linked to main documentation from README.md + +- Improved the content split between the project + overview page and the top level docs landing page diff --git a/docs/glossary.rst b/docs/glossary.rst index 618e433..c31e2a4 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -65,4 +65,4 @@ Essential Terms and Concepts An application layer with its supporting framework and base runtime layers. stack specification - A ``venvstacks.toml`` file that definez one or more environment stacks. + A ``venvstacks.toml`` file that defines one or more environment stacks. diff --git a/docs/index.rst b/docs/index.rst index 1afcf6f..7acdf1a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,42 @@ -.. venvstacks documentation master file, created by - sphinx-quickstart on Mon Oct 21 20:08:31 2024. +========================== +Virtual Environment Stacks +========================== -========================================== -Welcome to ``venvstacks``'s documentation! -========================================== +``venvstacks`` uses Python's ``sitecustomize.py`` environment setup feature +to chain together three layers of Python virtual environments: + +* "Runtime" layers: environments containing the desired version of a specific Python interpreter +* "Framework" layers: environments containing desired versions of key Python frameworks +* "Application" layers: environments containing components to be launched directly + +Application layer environments may include additional unpackaged Python launch modules or +packages for invocation with ``python``'s :external+py:option:`-m` switch. + +While the layers are archived and published separately, their dependency locking is integrated, +allowing the application layers to share dependencies installed in the framework layers, +and the framework layers to share dependencies installed in the runtime layers. + +Refer to the :ref:`overview` for an example of +specifying, locking, building, and publishing a set of environment stacks. + +.. _installing: + +``venvstacks`` is available from the :pypi:`Python Package Index `, +and can be installed with :pypi:`pipx` (or similar tools): + +.. code-block:: console + + $ pipx install venvstacks + +Alternatively, it can be installed as a user level package (although this may +make future Python version upgrades more irritating): + +.. code-block:: console + + $ pip install --user venvstacks .. toctree:: :maxdepth: 2 - :caption: Contents: overview glossary diff --git a/docs/overview.rst b/docs/overview.rst index 3a61833..c164dca 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,37 +1,13 @@ ----------------------------------- -Layered Virtual Environment Stacks ----------------------------------- +.. _overview: -``venvstacks`` uses Python's ``sitecustomize.py`` environment setup feature -to chain together three layers of Python virtual environments: +---------------- +Project Overview +---------------- -* "Runtime" layers: environments containing the desired version of a specific Python interpreter -* "Framework" layers: environments containing desired versions of key Python frameworks -* "Application" layers: environments containing components to be launched directly +Command line interface +====================== -While the layers are archived and published separately, their dependency locking is integrated, -allowing the application layers to share dependencies installed in the framework layers, -and the framework layers to share dependencies installed in the runtime layers. - - -Installing -========== - -``venvstacks`` is available from the :pypi:`Python Package Index `, -and can be installed with :pypi:`pipx` (or similar tools): - -.. code-block:: console - - $ pipx install venvstacks - -Alternatively, it can be installed as a user level package (although this may -make future Python version upgrades more irritating): - -.. code-block:: console - - $ pip install --user venvstacks - -The command line help also provides additional usage information: +The command line interface is the recommended interface for working with ``venvstacks``: .. code-block:: console @@ -51,14 +27,6 @@ The command line help also provides additional usage information: │ publish Publish layer archives for Python virtual environment stacks. │ ╰─────────────────────────────────────────────────────────────────────────────────╯ -.. note:: - - The ``venvstacks`` command is currently only available via the Python interpreter's - :py:option:`-m` switch, so Python command execution utilities like ``pipx run`` - and ``uvx`` don't work yet. - However, direct execution as ``venvstacks`` is expected to be - :issue:`supported in a future release <26>`. - Working with environment stacks =============================== diff --git a/pyproject.toml b/pyproject.toml index aa9f61a..373f4ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "venvstacks" -version = "0.1.0rc1" +version = "0.1.0rc1.post0" description = "Use layered Python virtual environment stacks to share large dependencies" authors = [ {name = "Alyssa Coghlan", email = "ncoghlan@gmail.com"}, @@ -49,6 +49,12 @@ rich-cli = [ [project.scripts] venvstacks = "venvstacks.cli:main" +[project.urls] +Homepage = "https://github.com/lmstudio-ai/venvstacks" +Documentation = "https://lmstudio-ai.github.io/venvstacks/" +Issues = "https://github.com/lmstudio-ai/venvstacks/issues" +Changelog = "https://lmstudio-ai.github.io/venvstacks/changelog/" + [build-system] requires = ["pdm-backend"] build-backend = "pdm.backend"