Initial documentation for venvstacks.toml (#82)

* 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 12, 2024 · 7877f74 · 7877f74
1 parent 1dc66f8
commit 7877f74
Show file tree

Hide file tree

Showing 23 changed files with 374 additions and 27 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
@@ -1,3 +1,5 @@
+"""Sphinx configuration for venvstacks documentation."""
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -28,12 +30,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"
@@ -57,12 +63,14 @@
     "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"),
+    "toml": ("https://toml.io/en/v1.0.0#%s", "%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