Initial restructuring of API docs (#54)

Also appropriately marks some symbols that shouldn't be accessed externally as private. Initial steps towards to addressing #33
lmstudio-ai · Oct 30, 2024 · fc68c3b · fc68c3b
1 parent ff058d1
commit fc68c3b
Show file tree

Hide file tree

Showing 45 changed files with 162 additions and 173 deletions.
diff --git a/docs/api/cli/index.rst b/docs/api/cli/index.rst
@@ -0,0 +1,12 @@
+venvstacks.cli
+==============
+
+.. warning::
+
+   The Python API is *NOT YET STABLE*.
+   Function, class, and method names may change between releases
+   without any deprecation period.
+
+.. automodule:: venvstacks.cli
+
+   .. autofunction:: main
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -12,9 +12,8 @@ Python API
 
    .. rubric:: Modules
 
-   .. autosummary::
-      :toctree:
+   .. toctree::
 
-      cli
-      pack_venv
-      stacks
+      cli/index
+      pack_venv/index
+      stacks/index
diff --git a/docs/api/pack_venv/index.rst b/docs/api/pack_venv/index.rst
@@ -0,0 +1,15 @@
+venvstacks.pack\_venv
+=====================
+
+.. warning::
+
+   The Python API is *NOT YET STABLE*.
+   Function, class, and method names may change between releases
+   without any deprecation period.
+
+.. automodule:: venvstacks.pack_venv
+
+   .. autofunction:: convert_symlinks
+   .. autofunction:: create_archive
+   .. autofunction:: export_venv
+   .. autofunction:: get_archive_path
diff --git a/docs/api/venvstacks.stacks.rst → docs/api/stacks/index.rst b/docs/api/venvstacks.stacks.rst → docs/api/stacks/index.rst
@@ -1,46 +1,95 @@
 venvstacks.stacks
 =================
 
+.. warning::
+
+   The Python API is *NOT YET STABLE*.
+   Function, class, and method names may change between releases
+   without any deprecation period.
+
 .. automodule:: venvstacks.stacks
 
+   .. rubric:: High Level Interface
 
-   .. rubric:: Classes
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
+      StackSpec
+      BuildEnvironment
+
+   .. rubric:: Layer Metadata Components
 
    .. autosummary::
       :toctree:
+      :nosignatures:
+
+      LayerCategories
+      LayerSpecMetadata
+      LayerVariants
+      TargetPlatform
+      TargetPlatforms
+
+   .. rubric:: Archive Publishing Results
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
 
-      ApplicationEnv
-      ApplicationSpec
       ArchiveBuildMetadata
       ArchiveBuildRequest
       ArchiveHashes
       ArchiveMetadata
-      BuildEnvironment
+      PublishedArchivePaths
+      StackPublishingRequest
+      StackPublishingResult
+
+   .. rubric:: Layer Export Results
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
       EnvironmentExportRequest
-      EnvironmentLock
-      EnvironmentLockMetadata
       ExportMetadata
       ExportedEnvironmentPaths
-      FrameworkEnv
+      StackExportRequest
+
+   .. rubric:: Layer Specifications
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
+      RuntimeSpec
       FrameworkSpec
-      PackageIndexConfig
-      LayerCategories
-      LayerSpecMetadata
-      LayerVariants
-      PublishedArchivePaths
+      ApplicationSpec
+
+   .. rubric:: Layer Build Environments
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
+      ApplicationEnv
+      FrameworkEnv
       RuntimeEnv
-      RuntimeSpec
-      StackExportRequest
-      StackPublishingRequest
-      StackPublishingResult
-      StackSpec
-      TargetPlatform
-      TargetPlatforms
+      EnvironmentLock
+      EnvironmentLockMetadata
+
+   .. rubric:: Build Process Configuration
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
+      PackageIndexConfig
 
    .. rubric:: Exceptions
 
    .. autosummary::
       :toctree:
+      :nosignatures:
 
       BuildEnvError
       EnvStackError

diff --git a/.../api/venvstacks.stacks.ApplicationEnv.rst → ...acks/venvstacks.stacks.ApplicationEnv.rst b/.../api/venvstacks.stacks.ApplicationEnv.rst → ...acks/venvstacks.stacks.ApplicationEnv.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.ApplicationEnv
 
 .. autoclass:: ApplicationEnv
 
-
-   .. automethod:: __init__
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/...api/venvstacks.stacks.ApplicationSpec.rst → ...cks/venvstacks.stacks.ApplicationSpec.rst b/...api/venvstacks.stacks.ApplicationSpec.rst → ...cks/venvstacks.stacks.ApplicationSpec.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.ApplicationSpec
 .. autoclass:: ApplicationSpec
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/...envstacks.stacks.ArchiveBuildMetadata.rst → ...envstacks.stacks.ArchiveBuildMetadata.rst b/...envstacks.stacks.ArchiveBuildMetadata.rst → ...envstacks.stacks.ArchiveBuildMetadata.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.ArchiveBuildMetadata
 
 .. autoclass:: ArchiveBuildMetadata
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/...venvstacks.stacks.ArchiveBuildRequest.rst → ...venvstacks.stacks.ArchiveBuildRequest.rst b/...venvstacks.stacks.ArchiveBuildRequest.rst → ...venvstacks.stacks.ArchiveBuildRequest.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.ArchiveBuildRequest
 .. autoclass:: ArchiveBuildRequest
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/docs/api/venvstacks.stacks.ArchiveHashes.rst → ...tacks/venvstacks.stacks.ArchiveHashes.rst b/docs/api/venvstacks.stacks.ArchiveHashes.rst → ...tacks/venvstacks.stacks.ArchiveHashes.rst
@@ -5,8 +5,6 @@ venvstacks.stacks.ArchiveHashes
 
 .. autoclass:: ArchiveHashes
 
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/...api/venvstacks.stacks.ArchiveMetadata.rst → ...cks/venvstacks.stacks.ArchiveMetadata.rst b/...api/venvstacks.stacks.ArchiveMetadata.rst → ...cks/venvstacks.stacks.ArchiveMetadata.rst
@@ -5,8 +5,6 @@ venvstacks.stacks.ArchiveMetadata
 
 .. autoclass:: ArchiveMetadata
 
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/venvstacks.stacks.BuildEnvError.rst → ...tacks/venvstacks.stacks.BuildEnvError.rst b/docs/api/venvstacks.stacks.BuildEnvError.rst → ...tacks/venvstacks.stacks.BuildEnvError.rst
diff --git a/...pi/venvstacks.stacks.BuildEnvironment.rst → ...ks/venvstacks.stacks.BuildEnvironment.rst b/...pi/venvstacks.stacks.BuildEnvironment.rst → ...ks/venvstacks.stacks.BuildEnvironment.rst
@@ -5,10 +5,6 @@ venvstacks.stacks.BuildEnvironment
 
 .. autoclass:: BuildEnvironment
 
-
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::
@@ -30,10 +26,6 @@ venvstacks.stacks.BuildEnvironment
       ~BuildEnvironment.select_layers
       ~BuildEnvironment.select_operations
       ~BuildEnvironment.venvstacks_to_build
-      ~BuildEnvironment.write_archive_metadata
-      ~BuildEnvironment.write_artifacts_manifest
-      ~BuildEnvironment.write_env_metadata
-      ~BuildEnvironment.write_export_manifest
 
    .. rubric:: Attributes
 

diff --git a/docs/api/venvstacks.stacks.EnvStackError.rst → ...tacks/venvstacks.stacks.EnvStackError.rst b/docs/api/venvstacks.stacks.EnvStackError.rst → ...tacks/venvstacks.stacks.EnvStackError.rst
diff --git a/...tacks.stacks.EnvironmentExportRequest.rst → ...tacks.stacks.EnvironmentExportRequest.rst b/...tacks.stacks.EnvironmentExportRequest.rst → ...tacks.stacks.EnvironmentExportRequest.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.EnvironmentExportRequest
 .. autoclass:: EnvironmentExportRequest
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/...api/venvstacks.stacks.EnvironmentLock.rst → ...cks/venvstacks.stacks.EnvironmentLock.rst b/...api/venvstacks.stacks.EnvironmentLock.rst → ...cks/venvstacks.stacks.EnvironmentLock.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.EnvironmentLock
 .. autoclass:: EnvironmentLock
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/...stacks.stacks.EnvironmentLockMetadata.rst → ...stacks.stacks.EnvironmentLockMetadata.rst b/...stacks.stacks.EnvironmentLockMetadata.rst → ...stacks.stacks.EnvironmentLockMetadata.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.EnvironmentLockMetadata
 
 .. autoclass:: EnvironmentLockMetadata
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/.../api/venvstacks.stacks.ExportMetadata.rst → ...acks/venvstacks.stacks.ExportMetadata.rst b/.../api/venvstacks.stacks.ExportMetadata.rst → ...acks/venvstacks.stacks.ExportMetadata.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.ExportMetadata
 
 .. autoclass:: ExportMetadata
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/...tacks.stacks.ExportedEnvironmentPaths.rst → ...tacks.stacks.ExportedEnvironmentPaths.rst b/...tacks.stacks.ExportedEnvironmentPaths.rst → ...tacks.stacks.ExportedEnvironmentPaths.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.ExportedEnvironmentPaths
 
 .. autoclass:: ExportedEnvironmentPaths
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/venvstacks.stacks.FrameworkEnv.rst → ...stacks/venvstacks.stacks.FrameworkEnv.rst b/docs/api/venvstacks.stacks.FrameworkEnv.rst → ...stacks/venvstacks.stacks.FrameworkEnv.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.FrameworkEnv
 .. autoclass:: FrameworkEnv
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/docs/api/venvstacks.stacks.FrameworkSpec.rst → ...tacks/venvstacks.stacks.FrameworkSpec.rst b/docs/api/venvstacks.stacks.FrameworkSpec.rst → ...tacks/venvstacks.stacks.FrameworkSpec.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.FrameworkSpec
 .. autoclass:: FrameworkSpec
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/...api/venvstacks.stacks.LayerCategories.rst → ...cks/venvstacks.stacks.LayerCategories.rst b/...api/venvstacks.stacks.LayerCategories.rst → ...cks/venvstacks.stacks.LayerCategories.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.LayerCategories
 
 .. autoclass:: LayerCategories
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/.../api/venvstacks.stacks.LayerSpecError.rst → ...acks/venvstacks.stacks.LayerSpecError.rst b/.../api/venvstacks.stacks.LayerSpecError.rst → ...acks/venvstacks.stacks.LayerSpecError.rst
diff --git a/...i/venvstacks.stacks.LayerSpecMetadata.rst → ...s/venvstacks.stacks.LayerSpecMetadata.rst b/...i/venvstacks.stacks.LayerSpecMetadata.rst → ...s/venvstacks.stacks.LayerSpecMetadata.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.LayerSpecMetadata
 
 .. autoclass:: LayerSpecMetadata
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/docs/api/venvstacks.stacks.LayerVariants.rst → ...tacks/venvstacks.stacks.LayerVariants.rst b/docs/api/venvstacks.stacks.LayerVariants.rst → ...tacks/venvstacks.stacks.LayerVariants.rst
@@ -5,9 +5,6 @@ venvstacks.stacks.LayerVariants
 
 .. autoclass:: LayerVariants
 
-
-   .. automethod:: __init__
-
    .. rubric:: Attributes
 
    .. autosummary::

diff --git a/.../venvstacks.stacks.PackageIndexConfig.rst → .../venvstacks.stacks.PackageIndexConfig.rst b/.../venvstacks.stacks.PackageIndexConfig.rst → .../venvstacks.stacks.PackageIndexConfig.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.PackageIndexConfig
 .. autoclass:: PackageIndexConfig
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/...nvstacks.stacks.PublishedArchivePaths.rst → ...nvstacks.stacks.PublishedArchivePaths.rst b/...nvstacks.stacks.PublishedArchivePaths.rst → ...nvstacks.stacks.PublishedArchivePaths.rst
diff --git a/docs/api/venvstacks.stacks.RuntimeEnv.rst → ...i/stacks/venvstacks.stacks.RuntimeEnv.rst b/docs/api/venvstacks.stacks.RuntimeEnv.rst → ...i/stacks/venvstacks.stacks.RuntimeEnv.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.RuntimeEnv
 .. autoclass:: RuntimeEnv
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/docs/api/venvstacks.stacks.RuntimeSpec.rst → .../stacks/venvstacks.stacks.RuntimeSpec.rst b/docs/api/venvstacks.stacks.RuntimeSpec.rst → .../stacks/venvstacks.stacks.RuntimeSpec.rst
@@ -6,9 +6,6 @@ venvstacks.stacks.RuntimeSpec
 .. autoclass:: RuntimeSpec
 
 
-   .. automethod:: __init__
-
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/.../venvstacks.stacks.StackExportRequest.rst → .../venvstacks.stacks.StackExportRequest.rst b/.../venvstacks.stacks.StackExportRequest.rst → .../venvstacks.stacks.StackExportRequest.rst
diff --git a/...vstacks.stacks.StackPublishingRequest.rst → ...vstacks.stacks.StackPublishingRequest.rst b/...vstacks.stacks.StackPublishingRequest.rst → ...vstacks.stacks.StackPublishingRequest.rst
diff --git a/...nvstacks.stacks.StackPublishingResult.rst → ...nvstacks.stacks.StackPublishingResult.rst b/...nvstacks.stacks.StackPublishingResult.rst → ...nvstacks.stacks.StackPublishingResult.rst
diff --git a/docs/api/venvstacks.stacks.StackSpec.rst → ...pi/stacks/venvstacks.stacks.StackSpec.rst b/docs/api/venvstacks.stacks.StackSpec.rst → ...pi/stacks/venvstacks.stacks.StackSpec.rst
@@ -5,8 +5,6 @@ venvstacks.stacks.StackSpec
 
 .. autoclass:: StackSpec
 
-   .. automethod:: __init__
-
    .. rubric:: Methods
 
    .. autosummary::

diff --git a/.../api/venvstacks.stacks.TargetPlatform.rst → ...acks/venvstacks.stacks.TargetPlatform.rst b/.../api/venvstacks.stacks.TargetPlatform.rst → ...acks/venvstacks.stacks.TargetPlatform.rst
diff --git a/...api/venvstacks.stacks.TargetPlatforms.rst → ...cks/venvstacks.stacks.TargetPlatforms.rst b/...api/venvstacks.stacks.TargetPlatforms.rst → ...cks/venvstacks.stacks.TargetPlatforms.rst
diff --git a/docs/api/venvstacks.cli.main.rst b/docs/api/venvstacks.cli.main.rst
diff --git a/docs/api/venvstacks.cli.rst b/docs/api/venvstacks.cli.rst