Require documentation of public API elements

* Enable docstring linting for public API elements * Linting enforces the use of Google-style docstrings * Update the names and visibility of various API elements * Add missing docstrings to public API elements * Fix some docstring text formatting issues * Add release notes for these changes and docs process changes Continues progress on issue #33 (improving the API docs).
lmstudio-ai · Nov 8, 2024 · 9c11877 · 9c11877
1 parent d5c3446
commit 9c11877
Show file tree

Hide file tree

Showing 36 changed files with 436 additions and 268 deletions.
diff --git a/changelog.d/20241108_215625_ncoghlan_enable_docstring_style_checks.rst b/changelog.d/20241108_215625_ncoghlan_enable_docstring_style_checks.rst
@@ -0,0 +1,11 @@
+Changed
+-------
+
+- Renamed :class:`!EnvironmentExportRequest` to :class:`LayerExportRequest` (part of :issue:`33`).
+- Exposed :class:`LayerSpecBase`, :class:`LayeredSpecBase` as public classes (part of :issue:`33`).
+- Exposed :class:`LayerEnvBase`, :class:`LayeredEnvBase` as public classes (part of :issue:`33`).
+- Added leading underscores to several private functions and methods (part of :issue:`33`).
+- Added docstrings to all remaining public functions and methods (part of :issue:`33`).
+- Enabled rendered previews for documentation PRs (requested in :issue:`43`).
+- Enabled link validity checks when rendering documentation (requested in :issue:`62`).
+
diff --git a/docs/api/stacks/index.rst b/docs/api/stacks/index.rst
@@ -50,7 +50,7 @@
       :toctree:
       :nosignatures:
 
-      EnvironmentExportRequest
+      LayerExportRequest
       ExportMetadata
       ExportedEnvironmentPaths
       StackExportRequest
@@ -61,7 +61,9 @@
       :toctree:
       :nosignatures:
 
+      LayerSpecBase
       RuntimeSpec
+      LayeredSpecBase
       FrameworkSpec
       ApplicationSpec
 
@@ -71,9 +73,11 @@
       :toctree:
       :nosignatures:
 
-      ApplicationEnv
-      FrameworkEnv
+      LayerEnvBase
       RuntimeEnv
+      LayeredEnvBase
+      FrameworkEnv
+      ApplicationEnv
       EnvironmentLock
       EnvironmentLockMetadata
 

diff --git a/docs/api/stacks/venvstacks.stacks.ApplicationEnv.rst b/docs/api/stacks/venvstacks.stacks.ApplicationEnv.rst
@@ -5,23 +5,6 @@ venvstacks.stacks.ApplicationEnv
 
 .. autoclass:: ApplicationEnv
 
-   .. rubric:: Methods
-
-   .. autosummary::
-
-      ~ApplicationEnv.create_archive
-      ~ApplicationEnv.create_environment
-      ~ApplicationEnv.define_archive_build
-      ~ApplicationEnv.export_environment
-      ~ApplicationEnv.get_constraint_paths
-      ~ApplicationEnv.install_requirements
-      ~ApplicationEnv.link_base_runtime
-      ~ApplicationEnv.link_layered_environments
-      ~ApplicationEnv.lock_requirements
-      ~ApplicationEnv.report_python_site_details
-      ~ApplicationEnv.request_export
-      ~ApplicationEnv.select_operations
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/stacks/venvstacks.stacks.ApplicationSpec.rst b/docs/api/stacks/venvstacks.stacks.ApplicationSpec.rst
@@ -5,14 +5,6 @@ venvstacks.stacks.ApplicationSpec
 
 .. autoclass:: ApplicationSpec
 
-
-   .. rubric:: Methods
-
-   .. autosummary::
-
-      ~ApplicationSpec.get_requirements_fname
-      ~ApplicationSpec.get_requirements_path
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/stacks/venvstacks.stacks.ArchiveBuildRequest.rst b/docs/api/stacks/venvstacks.stacks.ArchiveBuildRequest.rst
@@ -12,7 +12,6 @@ venvstacks.stacks.ArchiveBuildRequest
 
       ~ArchiveBuildRequest.create_archive
       ~ArchiveBuildRequest.define_build
-      ~ArchiveBuildRequest.needs_archive_build
 
    .. rubric:: Attributes
 

diff --git a/docs/api/stacks/venvstacks.stacks.EnvironmentExportRequest.rst b/docs/api/stacks/venvstacks.stacks.EnvironmentExportRequest.rst
diff --git a/docs/api/stacks/venvstacks.stacks.FrameworkSpec.rst b/docs/api/stacks/venvstacks.stacks.FrameworkSpec.rst
@@ -5,14 +5,6 @@ venvstacks.stacks.FrameworkSpec
 
 .. autoclass:: FrameworkSpec
 
-
-   .. rubric:: Methods
-
-   .. autosummary::
-
-      ~FrameworkSpec.get_requirements_fname
-      ~FrameworkSpec.get_requirements_path
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/stacks/venvstacks.stacks.LayerEnvBase.rst b/docs/api/stacks/venvstacks.stacks.LayerEnvBase.rst
@@ -0,0 +1,50 @@
+venvstacks.stacks.LayerEnvBase
+==============================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: LayerEnvBase
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~LayerEnvBase.create_archive
+      ~LayerEnvBase.create_environment
+      ~LayerEnvBase.define_archive_build
+      ~LayerEnvBase.export_environment
+      ~LayerEnvBase.get_constraint_paths
+      ~LayerEnvBase.install_requirements
+      ~LayerEnvBase.lock_requirements
+      ~LayerEnvBase.report_python_site_details
+      ~LayerEnvBase.request_export
+      ~LayerEnvBase.select_operations
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~LayerEnvBase.category
+      ~LayerEnvBase.env_name
+      ~LayerEnvBase.env_spec
+      ~LayerEnvBase.install_target
+      ~LayerEnvBase.kind
+      ~LayerEnvBase.want_build
+      ~LayerEnvBase.want_lock
+      ~LayerEnvBase.want_publish
+      ~LayerEnvBase.was_built
+      ~LayerEnvBase.was_created
+      ~LayerEnvBase.build_path
+      ~LayerEnvBase.requirements_path
+      ~LayerEnvBase.index_config
+      ~LayerEnvBase.env_path
+      ~LayerEnvBase.pylib_path
+      ~LayerEnvBase.dynlib_path
+      ~LayerEnvBase.executables_path
+      ~LayerEnvBase.python_path
+      ~LayerEnvBase.env_lock
+      ~LayerEnvBase.base_python_path
+      ~LayerEnvBase.tools_python_path
+      ~LayerEnvBase.py_version
+
diff --git a/docs/api/stacks/venvstacks.stacks.LayerExportRequest.rst b/docs/api/stacks/venvstacks.stacks.LayerExportRequest.rst
@@ -0,0 +1,25 @@
+venvstacks.stacks.LayerExportRequest
+====================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: LayerExportRequest
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~LayerExportRequest.define_export
+      ~LayerExportRequest.export_environment
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~LayerExportRequest.env_name
+      ~LayerExportRequest.env_lock
+      ~LayerExportRequest.export_path
+      ~LayerExportRequest.export_metadata
+      ~LayerExportRequest.needs_export
+
diff --git a/docs/api/stacks/venvstacks.stacks.LayerSpecBase.rst b/docs/api/stacks/venvstacks.stacks.LayerSpecBase.rst
@@ -0,0 +1,29 @@
+venvstacks.stacks.LayerSpecBase
+===============================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: LayerSpecBase
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~LayerSpecBase.get_requirements_fname
+      ~LayerSpecBase.get_requirements_path
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~LayerSpecBase.ENV_PREFIX
+      ~LayerSpecBase.category
+      ~LayerSpecBase.env_name
+      ~LayerSpecBase.kind
+      ~LayerSpecBase.name
+      ~LayerSpecBase.versioned
+      ~LayerSpecBase.requirements
+      ~LayerSpecBase.build_requirements
+      ~LayerSpecBase.platforms
+
diff --git a/docs/api/stacks/venvstacks.stacks.LayeredEnvBase.rst b/docs/api/stacks/venvstacks.stacks.LayeredEnvBase.rst
@@ -0,0 +1,36 @@
+venvstacks.stacks.LayeredEnvBase
+================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: LayeredEnvBase
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~LayeredEnvBase.base_runtime
+      ~LayeredEnvBase.category
+      ~LayeredEnvBase.env_name
+      ~LayeredEnvBase.env_spec
+      ~LayeredEnvBase.install_target
+      ~LayeredEnvBase.kind
+      ~LayeredEnvBase.linked_constraints_paths
+      ~LayeredEnvBase.want_build
+      ~LayeredEnvBase.want_lock
+      ~LayeredEnvBase.want_publish
+      ~LayeredEnvBase.was_built
+      ~LayeredEnvBase.was_created
+      ~LayeredEnvBase.build_path
+      ~LayeredEnvBase.requirements_path
+      ~LayeredEnvBase.index_config
+      ~LayeredEnvBase.env_path
+      ~LayeredEnvBase.pylib_path
+      ~LayeredEnvBase.dynlib_path
+      ~LayeredEnvBase.executables_path
+      ~LayeredEnvBase.python_path
+      ~LayeredEnvBase.env_lock
+      ~LayeredEnvBase.base_python_path
+      ~LayeredEnvBase.tools_python_path
+      ~LayeredEnvBase.py_version
+
diff --git a/docs/api/stacks/venvstacks.stacks.LayeredSpecBase.rst b/docs/api/stacks/venvstacks.stacks.LayeredSpecBase.rst
@@ -0,0 +1,22 @@
+venvstacks.stacks.LayeredSpecBase
+=================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: LayeredSpecBase
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~LayeredSpecBase.ENV_PREFIX
+      ~LayeredSpecBase.category
+      ~LayeredSpecBase.env_name
+      ~LayeredSpecBase.kind
+      ~LayeredSpecBase.runtime
+      ~LayeredSpecBase.name
+      ~LayeredSpecBase.versioned
+      ~LayeredSpecBase.requirements
+      ~LayeredSpecBase.build_requirements
+      ~LayeredSpecBase.platforms
+
diff --git a/docs/api/stacks/venvstacks.stacks.RuntimeEnv.rst b/docs/api/stacks/venvstacks.stacks.RuntimeEnv.rst
@@ -5,23 +5,6 @@ venvstacks.stacks.RuntimeEnv
 
 .. autoclass:: RuntimeEnv
 
-
-   .. rubric:: Methods
-
-   .. autosummary::
-
-      ~RuntimeEnv.create_archive
-      ~RuntimeEnv.create_build_environment
-      ~RuntimeEnv.create_environment
-      ~RuntimeEnv.define_archive_build
-      ~RuntimeEnv.export_environment
-      ~RuntimeEnv.get_constraint_paths
-      ~RuntimeEnv.install_requirements
-      ~RuntimeEnv.lock_requirements
-      ~RuntimeEnv.report_python_site_details
-      ~RuntimeEnv.request_export
-      ~RuntimeEnv.select_operations
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/stacks/venvstacks.stacks.RuntimeSpec.rst b/docs/api/stacks/venvstacks.stacks.RuntimeSpec.rst
@@ -5,14 +5,6 @@ venvstacks.stacks.RuntimeSpec
 
 .. autoclass:: RuntimeSpec
 
-
-   .. rubric:: Methods
-
-   .. autosummary::
-
-      ~RuntimeSpec.get_requirements_fname
-      ~RuntimeSpec.get_requirements_path
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,6 +22,7 @@
     "sphinx.ext.duration",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
 ]
 
 templates_path = ["_templates"]
@@ -49,6 +50,15 @@
 # (still using autodoc, but no generated stub files)
 autosummary_generate = False
 
+
+# -- Options for extlinks -------------------------------------------------------------
+
+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"),
+}
+
 # -- Options for intersphinx ----------------------------------------------------------
 
 intersphinx_mapping = {
@@ -57,10 +67,7 @@
 }
 
 
-# -- Options for extlinks -------------------------------------------------------------
+# -- Options for napoleon ------------------------------------------------------------
 
-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"),
-}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
diff --git a/misc/find_shared_libs.py b/misc/find_shared_libs.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Proof of concept for finding non-Python-module shared modules"""
+"""Proof of concept for finding non-Python-module shared modules."""
 
 # Concept demonstrator for the cross-environment shared library loading support
 # described in https://github.com/lmstudio-ai/venvstacks/issues/1
@@ -26,6 +26,7 @@ def _ext_to_suffixes(extension: str) -> tuple["str", ...]:
 
 
 def main() -> None:
+    """Find non-extension-module shared libraries in specified folder."""
     _dir_to_search = sys.argv[1]
     _paths_to_link = []
     for this_dir, _, files in os.walk(_dir_to_search):