Initial documentation for venvstacks.toml

* Add new docs page for file format details * Check release note snippets when building docs * Allow single backtick for inline literals in docs (and docstrings) * Add OpenGraph metadata for more pages * Fail the docs build on warnings * Allow passing args to the docs build when running locally Initial steps towards #78
lmstudio-ai · Nov 11, 2024 · 16c7d22 · 16c7d22
1 parent 1dc66f8
commit 16c7d22
Show file tree

Hide file tree

Showing 24 changed files with 388 additions and 35 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,17 +1,4 @@
-.. _changelog:
-
----------
-Changelog
----------
-
-.. note::
-
-   Until the Python API has stabilised, ``venvstacks`` is using
-   `ZeroVer <https://0ver.org/>`__ (starting from 0.1.0).
-
-   Refer to :ref:`version-numbering` for additional details
-   on the way releases are versioned.
-
+.. Included in published docs via docs/changelog.rst
 
 Unreleased
 ==========
@@ -20,7 +7,6 @@ See the fragment files in the `changelog.d directory`_.
 
 .. _changelog.d directory: https://github.com/lmstudio-ai/venvstacks/tree/main/changelog.d
 
-
 .. scriv-insert-here
 
 .. _changelog-0.1.1:
@@ -31,7 +17,8 @@ See the fragment files in the `changelog.d directory`_.
 Changed
 -------
 
-- Update docs URL to `https://venvstacks.lmstudio.ai`__
+- Update docs URL to
+  `https://venvstacks.lmstudio.ai <https://venvstacks.lmstudio.ai>`__
 
 - Add OpenGraph metadata to docs landing page
 
@@ -75,6 +62,6 @@ Changed
 Added
 -----
 
-- Initial export of `venvstacks` from Project Amphibian.
+- Initial export of ``venvstacks`` from Project Amphibian.
 
 - Adopted ``scriv`` for ``CHANGELOG`` management.
diff --git a/docs/api/cli/index.rst b/docs/api/cli/index.rst
@@ -1,6 +1,12 @@
 venvstacks.cli
 ==============
 
+.. meta::
+   :og:title: venvstacks.cli API - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/api/cli/
+   :og:description: venvstacks.cli Python API - venvstacks Documentation
+
 .. warning::
 
    The Python API is *NOT YET STABLE*.

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -2,6 +2,12 @@
 Python API
 ----------
 
+.. meta::
+   :og:title: venvstacks API - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/api/
+   :og:description: venvstacks Python API - venvstacks Documentation
+
 .. warning::
 
    The Python API is *NOT YET STABLE*.

diff --git a/docs/api/pack_venv/index.rst b/docs/api/pack_venv/index.rst
@@ -1,6 +1,12 @@
 venvstacks.pack\_venv
 =====================
 
+.. meta::
+   :og:title: venvstacks.pack_venv API - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/api/pack_venv/
+   :og:description: venvstacks.pack_venv Python API - venvstacks Documentation
+
 .. warning::
 
    The Python API is *NOT YET STABLE*.

diff --git a/docs/api/stacks/index.rst b/docs/api/stacks/index.rst
@@ -1,6 +1,24 @@
 venvstacks.stacks
 =================
 
+.. meta::
+   :og:title: venvstacks.stacks API - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/api/stacks/
+   :og:description: venvstacks.stacks Python API - venvstacks Documentation
+
+.. TODO: Replace the autosummary tables with:
+           * inline docs for the high level interface and the exceptions
+           * a stacks/metadata-details/ page
+           * a stacks/archive-publication/ page
+           * a stacks/local-exports/ page
+           * a stacks/layer-specifications/ page
+           * a stacks/layer-build-environments/ page
+           * a stacks/build-configuration/ page
+
+         Dedicated pages correspond to the sections below (except as noted).
+         Page names contain hyphens to ensure they're not valid submodule names.
+
 .. warning::
 
    The Python API is *NOT YET STABLE*.

diff --git a/...5_ncoghlan_more_resilient_postinstall.rst → ...5_ncoghlan_more_resilient_postinstall.rst b/...5_ncoghlan_more_resilient_postinstall.rst → ...5_ncoghlan_more_resilient_postinstall.rst
diff --git a/...oghlan_fix_automatic_layer_versioning.rst → ...oghlan_fix_automatic_layer_versioning.rst b/...oghlan_fix_automatic_layer_versioning.rst → ...oghlan_fix_automatic_layer_versioning.rst
diff --git a/...coghlan_enable_docstring_style_checks.rst → ...coghlan_enable_docstring_style_checks.rst b/...coghlan_enable_docstring_style_checks.rst → ...coghlan_enable_docstring_style_checks.rst
diff --git a/docs/changelog.d/20241111_104113_ncoghlan_add_stack_format_docs.rst b/docs/changelog.d/20241111_104113_ncoghlan_add_stack_format_docs.rst
@@ -0,0 +1,5 @@
+Added
+-----
+
+- Added documentation for the :ref:`stack-specification-format`.
+
diff --git a/changelog.d/README.txt → docs/changelog.d/README.txt b/changelog.d/README.txt → docs/changelog.d/README.txt
diff --git a/changelog.d/ghrel_template.md.j2 → docs/changelog.d/ghrel_template.md.j2 b/changelog.d/ghrel_template.md.j2 → docs/changelog.d/ghrel_template.md.j2
diff --git a/changelog.d/new_fragment.rst.j2 → docs/changelog.d/new_fragment.rst.j2 b/changelog.d/new_fragment.rst.j2 → docs/changelog.d/new_fragment.rst.j2
@@ -10,7 +10,7 @@
 .. "resolved" works for most categories, but replace the verb as necessary.
 .. Use `:pr:`NN` to refer to pull requests. Other Sphinx roles also work here.
 ..
-.. Deleting this header after editing is recommended.
+.. Deleting this header after editing is recommended (it contains 16 lines).
 
 Category
 --------

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1 +1,31 @@
+.. _changelog:
+
+---------
+Changelog
+---------
+
+.. meta::
+   :og:title: venvstacks Changelog - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/changelog/
+   :og:description: venvstacks Changelog - venvstacks Documentation
+
+.. note::
+
+   Until the Python API has stabilised, ``venvstacks`` is using
+   `ZeroVer <https://0ver.org/>`__ (starting from 0.1.0).
+
+   Refer to :ref:`version-numbering` for additional details
+   on the way releases are versioned.
+
+.. Syntax check the changelog fragments
+
+.. toctree::
+   :hidden:
+   :glob:
+
+   changelog.d/*
+
+.. Include the scriv-generated changelog details
+
 .. include:: ../CHANGELOG.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,12 +28,16 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# Allow Markdown-style single backtick syntax for inline literals
+default_role = "literal"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
 html_static_path = ["_static"]
+pygments_style = "sphinx"
+pygments_dark_style = "monokai"
 
 # Docs are published directly to GitHub pages, consider them to be unversioned
 html_title = "venvstacks documentation"
@@ -56,13 +60,15 @@
 extlinks = {
     "issue": ("https://github.com/lmstudio-ai/venvstacks/issues/%s", "#%s"),
     "pr": ("https://github.com/lmstudio-ai/venvstacks/pull/%s", "PR #%s"),
-    "pypi": ("https://pypi.org/project/%s/", "%s"),
+    "pypi": ("https://pypi.org/project/%s/", "``%s``"),
+    "toml": ("https://toml.io/en/v1.0.0#%s", "TOML %s"),
 }
+extlinks_detect_hardcoded_links = True
 
 # -- Options for intersphinx ----------------------------------------------------------
 
 intersphinx_mapping = {
-    "py": ("https://docs.python.org/3", None),
+    "pystd": ("https://docs.python.org/3", None),
     "packaging": ("https://packaging.python.org/en/latest/", None),
 }
 

diff --git a/docs/design.rst b/docs/design.rst
@@ -2,6 +2,12 @@
 Design Discussion
 -----------------
 
+.. meta::
+   :og:title: venvstacks Design - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/design/
+   :og:description: venvstacks Design Discussion - venvstacks Documentation
+
 Project
 =======
 

diff --git a/docs/development/index.rst b/docs/development/index.rst
@@ -4,6 +4,12 @@
 Development
 -----------
 
+.. meta::
+   :og:title: venvstacks Development - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/development/
+   :og:description: venvstacks Developer Guide - venvstacks Documentation
+
 
 Getting Started
 ===============
@@ -12,7 +18,8 @@ Getting Started
 
 This document aims to get you setup to work on venvstacks and to act as a guide
 and reference to the development setup. If you face any issues during this
-process, please `open an issue`_ about it on the issue tracker.
+process, please :issue:`open an issue <new?title=Trouble+with+development+environment>`
+about it on the issue tracker.
 
 
 Get the source code
@@ -279,7 +286,6 @@ After release:
 * Bump the version in ``pyproject.toml`` and add a ``.dev0`` suffix
 
 .. _`Getting Started`: https://pip.pypa.io/en/stable/development/getting-started/
-.. _`open an issue`: https://github.com/lmstudio-ai/venvstacks/issues/new?title=Trouble+with+development+environment
 .. _`rich CLI`: https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run
 .. _`GitHub`: https://github.com/lmstudio-ai/venvstacks
 .. _`testing README file`: https://github.com/lmstudio-ai/venvstacks/blob/main/tests/README.md

diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -1,7 +1,15 @@
+.. _glossary:
+
 ----------------------------
 Essential Terms and Concepts
 ----------------------------
 
+.. meta::
+   :og:title: venvstacks Glossary - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/glossary/
+   :og:description: venvstacks Glossary - venvstacks Documentation
+
 .. glossary::
 
    archive
@@ -60,6 +68,17 @@ Essential Terms and Concepts
         applications which embedding applications will invoke. Applications
         depend on one or more framework layers
 
+   layer category
+   layer kind
+   layer type
+     These terms all refer to the different categories of :term:`layer` that
+     ``venvstacks`` defines. In the code, ``kind`` refers to the singular
+     forms (``runtime``, ``framework``, ``application``), while ``category``
+     refers to the plural forms (``runtimes``, ``frameworks``, ``applications``).
+     The documentation will generally refer to layer types rather than layer
+     kinds (the code avoids this usage due to the potential confusion with
+     Python object types).
+
    stack
    environment stack
       An application layer with its supporting framework and base runtime layers.

diff --git a/docs/index.rst b/docs/index.rst
@@ -24,7 +24,7 @@ to chain together three layers of Python virtual environments:
 * "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 :py:option:`-m` switch.
+packages for invocation with ``python``'s :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,
@@ -54,6 +54,7 @@ make future Python version upgrades more irritating):
 
    overview
    glossary
+   stack-format
    design
    api/index
    development/index

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -4,6 +4,12 @@
 Project Overview
 ----------------
 
+.. meta::
+   :og:title: venvstacks Overview - venvstacks Documentation
+   :og:type: website
+   :og:url: https://venvstacks.lmstudio.ai/overview/
+   :og:description: venvstacks Project Overview - venvstacks Documentation
+
 Command line interface
 ======================