From b02ff460d7f6c2b82db207af382587c302f22f83 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Tue, 29 Oct 2024 18:48:42 +1000 Subject: [PATCH] Initial restructuring of API docs Also appropriately marks some symbols that shouldn't be accessed externally as private. Initial steps towards to addressing #33 --- docs/api/cli/index.rst | 12 +++ docs/api/index.rst | 9 +- docs/api/pack_venv/index.rst | 15 ++++ .../index.rst} | 87 +++++++++++++++---- .../venvstacks.stacks.ApplicationEnv.rst | 3 - .../venvstacks.stacks.ApplicationSpec.rst | 3 - ...venvstacks.stacks.ArchiveBuildMetadata.rst | 3 - .../venvstacks.stacks.ArchiveBuildRequest.rst | 3 - .../venvstacks.stacks.ArchiveHashes.rst | 2 - .../venvstacks.stacks.ArchiveMetadata.rst | 2 - .../venvstacks.stacks.BuildEnvError.rst | 0 .../venvstacks.stacks.BuildEnvironment.rst | 8 -- .../venvstacks.stacks.EnvStackError.rst | 0 ...stacks.stacks.EnvironmentExportRequest.rst | 3 - .../venvstacks.stacks.EnvironmentLock.rst | 3 - ...vstacks.stacks.EnvironmentLockMetadata.rst | 3 - .../venvstacks.stacks.ExportMetadata.rst | 3 - ...stacks.stacks.ExportedEnvironmentPaths.rst | 3 - .../venvstacks.stacks.FrameworkEnv.rst | 3 - .../venvstacks.stacks.FrameworkSpec.rst | 3 - .../venvstacks.stacks.LayerCategories.rst | 3 - .../venvstacks.stacks.LayerSpecError.rst | 0 .../venvstacks.stacks.LayerSpecMetadata.rst | 3 - .../venvstacks.stacks.LayerVariants.rst | 3 - .../venvstacks.stacks.PackageIndexConfig.rst | 3 - ...envstacks.stacks.PublishedArchivePaths.rst | 0 .../venvstacks.stacks.RuntimeEnv.rst | 3 - .../venvstacks.stacks.RuntimeSpec.rst | 3 - .../venvstacks.stacks.StackExportRequest.rst | 0 ...nvstacks.stacks.StackPublishingRequest.rst | 0 ...envstacks.stacks.StackPublishingResult.rst | 0 .../venvstacks.stacks.StackSpec.rst | 2 - .../venvstacks.stacks.TargetPlatform.rst | 0 .../venvstacks.stacks.TargetPlatforms.rst | 0 docs/api/venvstacks.cli.main.rst | 6 -- docs/api/venvstacks.cli.rst | 12 --- .../venvstacks.pack_venv.convert_symlinks.rst | 6 -- .../venvstacks.pack_venv.create_archive.rst | 6 -- docs/api/venvstacks.pack_venv.export_venv.rst | 6 -- .../venvstacks.pack_venv.get_archive_path.rst | 6 -- docs/api/venvstacks.pack_venv.rst | 15 ---- docs/conf.py | 5 +- docs/regen-api-docs.sh | 10 --- src/venvstacks/stacks.py | 68 +++++++++++++-- tox.ini | 7 -- 45 files changed, 162 insertions(+), 173 deletions(-) create mode 100644 docs/api/cli/index.rst create mode 100644 docs/api/pack_venv/index.rst rename docs/api/{venvstacks.stacks.rst => stacks/index.rst} (51%) rename docs/api/{ => stacks}/venvstacks.stacks.ApplicationEnv.rst (98%) rename docs/api/{ => stacks}/venvstacks.stacks.ApplicationSpec.rst (96%) rename docs/api/{ => stacks}/venvstacks.stacks.ArchiveBuildMetadata.rst (95%) rename docs/api/{ => stacks}/venvstacks.stacks.ArchiveBuildRequest.rst (95%) rename docs/api/{ => stacks}/venvstacks.stacks.ArchiveHashes.rst (87%) rename docs/api/{ => stacks}/venvstacks.stacks.ArchiveMetadata.rst (96%) rename docs/api/{ => stacks}/venvstacks.stacks.BuildEnvError.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.BuildEnvironment.rst (86%) rename docs/api/{ => stacks}/venvstacks.stacks.EnvStackError.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.EnvironmentExportRequest.rst (95%) rename docs/api/{ => stacks}/venvstacks.stacks.EnvironmentLock.rst (95%) rename docs/api/{ => stacks}/venvstacks.stacks.EnvironmentLockMetadata.rst (92%) rename docs/api/{ => stacks}/venvstacks.stacks.ExportMetadata.rst (94%) rename docs/api/{ => stacks}/venvstacks.stacks.ExportedEnvironmentPaths.rst (92%) rename docs/api/{ => stacks}/venvstacks.stacks.FrameworkEnv.rst (97%) rename docs/api/{ => stacks}/venvstacks.stacks.FrameworkSpec.rst (95%) rename docs/api/{ => stacks}/venvstacks.stacks.LayerCategories.rst (90%) rename docs/api/{ => stacks}/venvstacks.stacks.LayerSpecError.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.LayerSpecMetadata.rst (94%) rename docs/api/{ => stacks}/venvstacks.stacks.LayerVariants.rst (90%) rename docs/api/{ => stacks}/venvstacks.stacks.PackageIndexConfig.rst (93%) rename docs/api/{ => stacks}/venvstacks.stacks.PublishedArchivePaths.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.RuntimeEnv.rst (97%) rename docs/api/{ => stacks}/venvstacks.stacks.RuntimeSpec.rst (95%) rename docs/api/{ => stacks}/venvstacks.stacks.StackExportRequest.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.StackPublishingRequest.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.StackPublishingResult.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.StackSpec.rst (94%) rename docs/api/{ => stacks}/venvstacks.stacks.TargetPlatform.rst (100%) rename docs/api/{ => stacks}/venvstacks.stacks.TargetPlatforms.rst (100%) delete mode 100644 docs/api/venvstacks.cli.main.rst delete mode 100644 docs/api/venvstacks.cli.rst delete mode 100644 docs/api/venvstacks.pack_venv.convert_symlinks.rst delete mode 100644 docs/api/venvstacks.pack_venv.create_archive.rst delete mode 100644 docs/api/venvstacks.pack_venv.export_venv.rst delete mode 100644 docs/api/venvstacks.pack_venv.get_archive_path.rst delete mode 100644 docs/api/venvstacks.pack_venv.rst delete mode 100755 docs/regen-api-docs.sh diff --git a/docs/api/cli/index.rst b/docs/api/cli/index.rst new file mode 100644 index 0000000..14528fd --- /dev/null +++ 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 index 490eb36..4858fdc 100644 --- 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 new file mode 100644 index 0000000..f9f216c --- /dev/null +++ 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 b/docs/api/stacks/index.rst similarity index 51% rename from docs/api/venvstacks.stacks.rst rename to docs/api/stacks/index.rst index 458c9fd..4f83160 100644 --- a/docs/api/venvstacks.stacks.rst +++ b/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/docs/api/venvstacks.stacks.ApplicationEnv.rst b/docs/api/stacks/venvstacks.stacks.ApplicationEnv.rst similarity index 98% rename from docs/api/venvstacks.stacks.ApplicationEnv.rst rename to docs/api/stacks/venvstacks.stacks.ApplicationEnv.rst index c796d6a..8fa92f4 100644 --- a/docs/api/venvstacks.stacks.ApplicationEnv.rst +++ b/docs/api/stacks/venvstacks.stacks.ApplicationEnv.rst @@ -5,9 +5,6 @@ venvstacks.stacks.ApplicationEnv .. autoclass:: ApplicationEnv - - .. automethod:: __init__ - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.ApplicationSpec.rst b/docs/api/stacks/venvstacks.stacks.ApplicationSpec.rst similarity index 96% rename from docs/api/venvstacks.stacks.ApplicationSpec.rst rename to docs/api/stacks/venvstacks.stacks.ApplicationSpec.rst index 5564fc4..8168faf 100644 --- a/docs/api/venvstacks.stacks.ApplicationSpec.rst +++ b/docs/api/stacks/venvstacks.stacks.ApplicationSpec.rst @@ -6,9 +6,6 @@ venvstacks.stacks.ApplicationSpec .. autoclass:: ApplicationSpec - .. automethod:: __init__ - - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.ArchiveBuildMetadata.rst b/docs/api/stacks/venvstacks.stacks.ArchiveBuildMetadata.rst similarity index 95% rename from docs/api/venvstacks.stacks.ArchiveBuildMetadata.rst rename to docs/api/stacks/venvstacks.stacks.ArchiveBuildMetadata.rst index b6fdfc2..8b003ce 100644 --- a/docs/api/venvstacks.stacks.ArchiveBuildMetadata.rst +++ b/docs/api/stacks/venvstacks.stacks.ArchiveBuildMetadata.rst @@ -5,9 +5,6 @@ venvstacks.stacks.ArchiveBuildMetadata .. autoclass:: ArchiveBuildMetadata - - .. automethod:: __init__ - .. rubric:: Attributes .. autosummary:: diff --git a/docs/api/venvstacks.stacks.ArchiveBuildRequest.rst b/docs/api/stacks/venvstacks.stacks.ArchiveBuildRequest.rst similarity index 95% rename from docs/api/venvstacks.stacks.ArchiveBuildRequest.rst rename to docs/api/stacks/venvstacks.stacks.ArchiveBuildRequest.rst index a428119..f248b44 100644 --- a/docs/api/venvstacks.stacks.ArchiveBuildRequest.rst +++ b/docs/api/stacks/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 b/docs/api/stacks/venvstacks.stacks.ArchiveHashes.rst similarity index 87% rename from docs/api/venvstacks.stacks.ArchiveHashes.rst rename to docs/api/stacks/venvstacks.stacks.ArchiveHashes.rst index 9f39536..2065c1e 100644 --- a/docs/api/venvstacks.stacks.ArchiveHashes.rst +++ b/docs/api/stacks/venvstacks.stacks.ArchiveHashes.rst @@ -5,8 +5,6 @@ venvstacks.stacks.ArchiveHashes .. autoclass:: ArchiveHashes - .. automethod:: __init__ - .. rubric:: Attributes .. autosummary:: diff --git a/docs/api/venvstacks.stacks.ArchiveMetadata.rst b/docs/api/stacks/venvstacks.stacks.ArchiveMetadata.rst similarity index 96% rename from docs/api/venvstacks.stacks.ArchiveMetadata.rst rename to docs/api/stacks/venvstacks.stacks.ArchiveMetadata.rst index c9035ba..8326f81 100644 --- a/docs/api/venvstacks.stacks.ArchiveMetadata.rst +++ b/docs/api/stacks/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 b/docs/api/stacks/venvstacks.stacks.BuildEnvError.rst similarity index 100% rename from docs/api/venvstacks.stacks.BuildEnvError.rst rename to docs/api/stacks/venvstacks.stacks.BuildEnvError.rst diff --git a/docs/api/venvstacks.stacks.BuildEnvironment.rst b/docs/api/stacks/venvstacks.stacks.BuildEnvironment.rst similarity index 86% rename from docs/api/venvstacks.stacks.BuildEnvironment.rst rename to docs/api/stacks/venvstacks.stacks.BuildEnvironment.rst index 4b11373..4aed473 100644 --- a/docs/api/venvstacks.stacks.BuildEnvironment.rst +++ b/docs/api/stacks/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 b/docs/api/stacks/venvstacks.stacks.EnvStackError.rst similarity index 100% rename from docs/api/venvstacks.stacks.EnvStackError.rst rename to docs/api/stacks/venvstacks.stacks.EnvStackError.rst diff --git a/docs/api/venvstacks.stacks.EnvironmentExportRequest.rst b/docs/api/stacks/venvstacks.stacks.EnvironmentExportRequest.rst similarity index 95% rename from docs/api/venvstacks.stacks.EnvironmentExportRequest.rst rename to docs/api/stacks/venvstacks.stacks.EnvironmentExportRequest.rst index 3f253a0..75e4758 100644 --- a/docs/api/venvstacks.stacks.EnvironmentExportRequest.rst +++ b/docs/api/stacks/venvstacks.stacks.EnvironmentExportRequest.rst @@ -6,9 +6,6 @@ venvstacks.stacks.EnvironmentExportRequest .. autoclass:: EnvironmentExportRequest - .. automethod:: __init__ - - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.EnvironmentLock.rst b/docs/api/stacks/venvstacks.stacks.EnvironmentLock.rst similarity index 95% rename from docs/api/venvstacks.stacks.EnvironmentLock.rst rename to docs/api/stacks/venvstacks.stacks.EnvironmentLock.rst index 6382e6e..57f92dd 100644 --- a/docs/api/venvstacks.stacks.EnvironmentLock.rst +++ b/docs/api/stacks/venvstacks.stacks.EnvironmentLock.rst @@ -6,9 +6,6 @@ venvstacks.stacks.EnvironmentLock .. autoclass:: EnvironmentLock - .. automethod:: __init__ - - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.EnvironmentLockMetadata.rst b/docs/api/stacks/venvstacks.stacks.EnvironmentLockMetadata.rst similarity index 92% rename from docs/api/venvstacks.stacks.EnvironmentLockMetadata.rst rename to docs/api/stacks/venvstacks.stacks.EnvironmentLockMetadata.rst index a8f20f6..7f11b4c 100644 --- a/docs/api/venvstacks.stacks.EnvironmentLockMetadata.rst +++ b/docs/api/stacks/venvstacks.stacks.EnvironmentLockMetadata.rst @@ -5,9 +5,6 @@ venvstacks.stacks.EnvironmentLockMetadata .. autoclass:: EnvironmentLockMetadata - - .. automethod:: __init__ - .. rubric:: Attributes .. autosummary:: diff --git a/docs/api/venvstacks.stacks.ExportMetadata.rst b/docs/api/stacks/venvstacks.stacks.ExportMetadata.rst similarity index 94% rename from docs/api/venvstacks.stacks.ExportMetadata.rst rename to docs/api/stacks/venvstacks.stacks.ExportMetadata.rst index 6881e39..6dd1df0 100644 --- a/docs/api/venvstacks.stacks.ExportMetadata.rst +++ b/docs/api/stacks/venvstacks.stacks.ExportMetadata.rst @@ -5,9 +5,6 @@ venvstacks.stacks.ExportMetadata .. autoclass:: ExportMetadata - - .. automethod:: __init__ - .. rubric:: Attributes .. autosummary:: diff --git a/docs/api/venvstacks.stacks.ExportedEnvironmentPaths.rst b/docs/api/stacks/venvstacks.stacks.ExportedEnvironmentPaths.rst similarity index 92% rename from docs/api/venvstacks.stacks.ExportedEnvironmentPaths.rst rename to docs/api/stacks/venvstacks.stacks.ExportedEnvironmentPaths.rst index 9cb30cb..b58757e 100644 --- a/docs/api/venvstacks.stacks.ExportedEnvironmentPaths.rst +++ b/docs/api/stacks/venvstacks.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 b/docs/api/stacks/venvstacks.stacks.FrameworkEnv.rst similarity index 97% rename from docs/api/venvstacks.stacks.FrameworkEnv.rst rename to docs/api/stacks/venvstacks.stacks.FrameworkEnv.rst index dfde998..14e21ee 100644 --- a/docs/api/venvstacks.stacks.FrameworkEnv.rst +++ b/docs/api/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 b/docs/api/stacks/venvstacks.stacks.FrameworkSpec.rst similarity index 95% rename from docs/api/venvstacks.stacks.FrameworkSpec.rst rename to docs/api/stacks/venvstacks.stacks.FrameworkSpec.rst index cd226b7..a871f09 100644 --- a/docs/api/venvstacks.stacks.FrameworkSpec.rst +++ b/docs/api/stacks/venvstacks.stacks.FrameworkSpec.rst @@ -6,9 +6,6 @@ venvstacks.stacks.FrameworkSpec .. autoclass:: FrameworkSpec - .. automethod:: __init__ - - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.LayerCategories.rst b/docs/api/stacks/venvstacks.stacks.LayerCategories.rst similarity index 90% rename from docs/api/venvstacks.stacks.LayerCategories.rst rename to docs/api/stacks/venvstacks.stacks.LayerCategories.rst index cf56500..cf8b8ff 100644 --- a/docs/api/venvstacks.stacks.LayerCategories.rst +++ b/docs/api/stacks/venvstacks.stacks.LayerCategories.rst @@ -5,9 +5,6 @@ venvstacks.stacks.LayerCategories .. autoclass:: LayerCategories - - .. automethod:: __init__ - .. rubric:: Attributes .. autosummary:: diff --git a/docs/api/venvstacks.stacks.LayerSpecError.rst b/docs/api/stacks/venvstacks.stacks.LayerSpecError.rst similarity index 100% rename from docs/api/venvstacks.stacks.LayerSpecError.rst rename to docs/api/stacks/venvstacks.stacks.LayerSpecError.rst diff --git a/docs/api/venvstacks.stacks.LayerSpecMetadata.rst b/docs/api/stacks/venvstacks.stacks.LayerSpecMetadata.rst similarity index 94% rename from docs/api/venvstacks.stacks.LayerSpecMetadata.rst rename to docs/api/stacks/venvstacks.stacks.LayerSpecMetadata.rst index a6b4ddc..9bc61cd 100644 --- a/docs/api/venvstacks.stacks.LayerSpecMetadata.rst +++ b/docs/api/stacks/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 b/docs/api/stacks/venvstacks.stacks.LayerVariants.rst similarity index 90% rename from docs/api/venvstacks.stacks.LayerVariants.rst rename to docs/api/stacks/venvstacks.stacks.LayerVariants.rst index 33cfb24..461c09b 100644 --- a/docs/api/venvstacks.stacks.LayerVariants.rst +++ b/docs/api/stacks/venvstacks.stacks.LayerVariants.rst @@ -5,9 +5,6 @@ venvstacks.stacks.LayerVariants .. autoclass:: LayerVariants - - .. automethod:: __init__ - .. rubric:: Attributes .. autosummary:: diff --git a/docs/api/venvstacks.stacks.PackageIndexConfig.rst b/docs/api/stacks/venvstacks.stacks.PackageIndexConfig.rst similarity index 93% rename from docs/api/venvstacks.stacks.PackageIndexConfig.rst rename to docs/api/stacks/venvstacks.stacks.PackageIndexConfig.rst index 7288eca..66c07ce 100644 --- a/docs/api/venvstacks.stacks.PackageIndexConfig.rst +++ b/docs/api/stacks/venvstacks.stacks.PackageIndexConfig.rst @@ -6,9 +6,6 @@ venvstacks.stacks.PackageIndexConfig .. autoclass:: PackageIndexConfig - .. automethod:: __init__ - - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.PublishedArchivePaths.rst b/docs/api/stacks/venvstacks.stacks.PublishedArchivePaths.rst similarity index 100% rename from docs/api/venvstacks.stacks.PublishedArchivePaths.rst rename to docs/api/stacks/venvstacks.stacks.PublishedArchivePaths.rst diff --git a/docs/api/venvstacks.stacks.RuntimeEnv.rst b/docs/api/stacks/venvstacks.stacks.RuntimeEnv.rst similarity index 97% rename from docs/api/venvstacks.stacks.RuntimeEnv.rst rename to docs/api/stacks/venvstacks.stacks.RuntimeEnv.rst index ddecd61..836ec81 100644 --- a/docs/api/venvstacks.stacks.RuntimeEnv.rst +++ b/docs/api/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 b/docs/api/stacks/venvstacks.stacks.RuntimeSpec.rst similarity index 95% rename from docs/api/venvstacks.stacks.RuntimeSpec.rst rename to docs/api/stacks/venvstacks.stacks.RuntimeSpec.rst index 5d14888..0298f29 100644 --- a/docs/api/venvstacks.stacks.RuntimeSpec.rst +++ b/docs/api/stacks/venvstacks.stacks.RuntimeSpec.rst @@ -6,9 +6,6 @@ venvstacks.stacks.RuntimeSpec .. autoclass:: RuntimeSpec - .. automethod:: __init__ - - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.StackExportRequest.rst b/docs/api/stacks/venvstacks.stacks.StackExportRequest.rst similarity index 100% rename from docs/api/venvstacks.stacks.StackExportRequest.rst rename to docs/api/stacks/venvstacks.stacks.StackExportRequest.rst diff --git a/docs/api/venvstacks.stacks.StackPublishingRequest.rst b/docs/api/stacks/venvstacks.stacks.StackPublishingRequest.rst similarity index 100% rename from docs/api/venvstacks.stacks.StackPublishingRequest.rst rename to docs/api/stacks/venvstacks.stacks.StackPublishingRequest.rst diff --git a/docs/api/venvstacks.stacks.StackPublishingResult.rst b/docs/api/stacks/venvstacks.stacks.StackPublishingResult.rst similarity index 100% rename from docs/api/venvstacks.stacks.StackPublishingResult.rst rename to docs/api/stacks/venvstacks.stacks.StackPublishingResult.rst diff --git a/docs/api/venvstacks.stacks.StackSpec.rst b/docs/api/stacks/venvstacks.stacks.StackSpec.rst similarity index 94% rename from docs/api/venvstacks.stacks.StackSpec.rst rename to docs/api/stacks/venvstacks.stacks.StackSpec.rst index dfa0841..174e0d6 100644 --- a/docs/api/venvstacks.stacks.StackSpec.rst +++ b/docs/api/stacks/venvstacks.stacks.StackSpec.rst @@ -5,8 +5,6 @@ venvstacks.stacks.StackSpec .. autoclass:: StackSpec - .. automethod:: __init__ - .. rubric:: Methods .. autosummary:: diff --git a/docs/api/venvstacks.stacks.TargetPlatform.rst b/docs/api/stacks/venvstacks.stacks.TargetPlatform.rst similarity index 100% rename from docs/api/venvstacks.stacks.TargetPlatform.rst rename to docs/api/stacks/venvstacks.stacks.TargetPlatform.rst diff --git a/docs/api/venvstacks.stacks.TargetPlatforms.rst b/docs/api/stacks/venvstacks.stacks.TargetPlatforms.rst similarity index 100% rename from docs/api/venvstacks.stacks.TargetPlatforms.rst rename to docs/api/stacks/venvstacks.stacks.TargetPlatforms.rst diff --git a/docs/api/venvstacks.cli.main.rst b/docs/api/venvstacks.cli.main.rst deleted file mode 100644 index 2925f3a..0000000 --- a/docs/api/venvstacks.cli.main.rst +++ /dev/null @@ -1,6 +0,0 @@ -venvstacks.cli.main -=================== - -.. currentmodule:: venvstacks.cli - -.. autofunction:: main \ No newline at end of file diff --git a/docs/api/venvstacks.cli.rst b/docs/api/venvstacks.cli.rst deleted file mode 100644 index dbc55b2..0000000 --- a/docs/api/venvstacks.cli.rst +++ /dev/null @@ -1,12 +0,0 @@ -venvstacks.cli -============== - -.. automodule:: venvstacks.cli - - - .. rubric:: Functions - - .. autosummary:: - :toctree: - - main diff --git a/docs/api/venvstacks.pack_venv.convert_symlinks.rst b/docs/api/venvstacks.pack_venv.convert_symlinks.rst deleted file mode 100644 index 5f4cb09..0000000 --- a/docs/api/venvstacks.pack_venv.convert_symlinks.rst +++ /dev/null @@ -1,6 +0,0 @@ -venvstacks.pack\_venv.convert\_symlinks -======================================= - -.. currentmodule:: venvstacks.pack_venv - -.. autofunction:: convert_symlinks \ No newline at end of file diff --git a/docs/api/venvstacks.pack_venv.create_archive.rst b/docs/api/venvstacks.pack_venv.create_archive.rst deleted file mode 100644 index ad073d8..0000000 --- a/docs/api/venvstacks.pack_venv.create_archive.rst +++ /dev/null @@ -1,6 +0,0 @@ -venvstacks.pack\_venv.create\_archive -===================================== - -.. currentmodule:: venvstacks.pack_venv - -.. autofunction:: create_archive \ No newline at end of file diff --git a/docs/api/venvstacks.pack_venv.export_venv.rst b/docs/api/venvstacks.pack_venv.export_venv.rst deleted file mode 100644 index 0003c3b..0000000 --- a/docs/api/venvstacks.pack_venv.export_venv.rst +++ /dev/null @@ -1,6 +0,0 @@ -venvstacks.pack\_venv.export\_venv -================================== - -.. currentmodule:: venvstacks.pack_venv - -.. autofunction:: export_venv \ No newline at end of file diff --git a/docs/api/venvstacks.pack_venv.get_archive_path.rst b/docs/api/venvstacks.pack_venv.get_archive_path.rst deleted file mode 100644 index 9d11246..0000000 --- a/docs/api/venvstacks.pack_venv.get_archive_path.rst +++ /dev/null @@ -1,6 +0,0 @@ -venvstacks.pack\_venv.get\_archive\_path -======================================== - -.. currentmodule:: venvstacks.pack_venv - -.. autofunction:: get_archive_path \ No newline at end of file diff --git a/docs/api/venvstacks.pack_venv.rst b/docs/api/venvstacks.pack_venv.rst deleted file mode 100644 index 27cda38..0000000 --- a/docs/api/venvstacks.pack_venv.rst +++ /dev/null @@ -1,15 +0,0 @@ -venvstacks.pack\_venv -===================== - -.. automodule:: venvstacks.pack_venv - - - .. rubric:: Functions - - .. autosummary:: - :toctree: - - convert_symlinks - create_archive - export_venv - get_archive_path diff --git a/docs/conf.py b/docs/conf.py index 4b81529..dbe4582 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,9 +39,10 @@ html_use_index = False -# -- Options for intersphinx ---------------------------------------------------------- +# -- Options for autosummary ---------------------------------------------------------- -# Run `tox -e regen-apidocs` to regenerate the API stub pages +# API docs are being migrated over to custom narrative documentation +# (still using autodoc, but no generated stub files) autosummary_generate = False # -- Options for intersphinx ---------------------------------------------------------- diff --git a/docs/regen-api-docs.sh b/docs/regen-api-docs.sh deleted file mode 100755 index 241c285..0000000 --- a/docs/regen-api-docs.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/bash - -# See http://redsymbol.net/articles/unofficial-bash-strict-mode/ for benefit of these options -set -euo pipefail -IFS=$'\n\t' - -echo "API docs regen disabled by default (as it overwrites existing edits)" -exit 1 - -# sphinx-autogen -o docs/api docs/api/venvstacks.*.rst diff --git a/src/venvstacks/stacks.py b/src/venvstacks/stacks.py index b2b1bb8..5ba244b 100755 --- a/src/venvstacks/stacks.py +++ b/src/venvstacks/stacks.py @@ -173,6 +173,8 @@ def _get_pip_install_args(self) -> list[str]: class EnvironmentLockMetadata(TypedDict): + """Details of the last time this environment was locked""" + # fmt: off locked_at: str # ISO formatted date/time value requirements_hash: str # Uses "algorithm:hexdigest" format @@ -185,6 +187,8 @@ class EnvironmentLockMetadata(TypedDict): @dataclass class EnvironmentLock: + """Layered environment dependency locking management""" + requirements_path: Path versioned: bool lock_metadata_path: Path = field(init=False, repr=False) @@ -342,6 +346,8 @@ def update_lock_metadata(self) -> bool: # https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#basic-platform-tags # macOS target system API version info is omitted (as that will be set universally for macOS builds) class TargetPlatforms(StrEnum): + """Enum for support target deployment platforms""" + WINDOWS = "win_amd64" LINUX = "linux_x86_64" MACOS_APPLE = "macosx_arm64" @@ -367,12 +373,16 @@ def ensure_platform_list(cls, metadata: MutableMapping[str, Any]) -> None: class LayerVariants(StrEnum): + """Enum for defined layer variants""" + RUNTIME = "runtime" FRAMEWORK = "framework" APPLICATION = "application" class LayerCategories(StrEnum): + """Enum for defined layer categories (collections of each variant)""" + RUNTIMES = "runtimes" FRAMEWORKS = "frameworks" APPLICATIONS = "applications" @@ -433,6 +443,8 @@ def get_requirements_path(self, platform: str, requirements_dir: StrPath) -> Pat @dataclass class RuntimeSpec(_PythonEnvironmentSpec): + """Base runtime layer specification""" + kind = LayerVariants.RUNTIME category = LayerCategories.RUNTIMES fully_versioned_name: str = field(repr=False) @@ -452,6 +464,8 @@ class _VirtualEnvironmentSpec(_PythonEnvironmentSpec): @dataclass class FrameworkSpec(_VirtualEnvironmentSpec): + """Framework layer specification""" + ENV_PREFIX = "framework" kind = LayerVariants.FRAMEWORK category = LayerCategories.FRAMEWORKS @@ -459,6 +473,8 @@ class FrameworkSpec(_VirtualEnvironmentSpec): @dataclass class ApplicationSpec(_VirtualEnvironmentSpec): + """Application layer specification""" + ENV_PREFIX = "app" kind = LayerVariants.APPLICATION category = LayerCategories.APPLICATIONS @@ -467,6 +483,8 @@ class ApplicationSpec(_VirtualEnvironmentSpec): class LayerSpecMetadata(TypedDict): + """Details of a defined environment layer""" + # fmt: off # Common fields defined for all layers, whether archived or exported layer_name: EnvNameBuild # Prefixed layer name without lock version info @@ -500,6 +518,8 @@ class LayerSpecMetadata(TypedDict): class ArchiveHashes(TypedDict): + """Hash details of a built archive""" + sha256: str # Only SHA256 hashes for now. Mark both old and new hash fields with `typing.NotRequired` # to migrate to a different hashing function in the future. @@ -681,6 +701,8 @@ class StackPublishingResult(TypedDict): class PublishedArchivePaths(NamedTuple): + """Locations of published metadata and archive files""" + metadata_path: Path snippet_paths: list[Path] archive_paths: list[Path] @@ -811,10 +833,14 @@ def _run_postinstall(export_path: Path, postinstall_path: Path) -> None: class StackExportRequest(TypedDict): + """Inputs to an environment export request for a full stack specification""" + layers: LayeredExportMetadata class ExportedEnvironmentPaths(NamedTuple): + """Locations of exported metadata files and deployed environments""" + metadata_path: Path snippet_paths: list[Path] env_paths: list[Path] @@ -1317,6 +1343,8 @@ def export_environment( class RuntimeEnv(_PythonEnvironment): + """Base runtime layer build environment""" + kind = LayerVariants.RUNTIME category = LayerCategories.RUNTIMES @@ -1467,6 +1495,8 @@ def _update_output_metadata(self, metadata: LayerSpecMetadata) -> None: class FrameworkEnv(_VirtualEnvironment): + """Framework layer build environment""" + kind = LayerVariants.FRAMEWORK category = LayerCategories.FRAMEWORKS _include_system_site_packages = True @@ -1479,6 +1509,8 @@ def env_spec(self) -> FrameworkSpec: class ApplicationEnv(_VirtualEnvironment): + """Application layer build environment""" + kind = LayerVariants.APPLICATION category = LayerCategories.APPLICATIONS @@ -1624,6 +1656,8 @@ def _update_output_metadata(self, metadata: LayerSpecMetadata) -> None: @dataclass class StackSpec: + """Layered environment stack specification""" + # Specified on creation spec_path: Path runtimes: MutableMapping[LayerBaseName, RuntimeSpec] @@ -1644,6 +1678,8 @@ def __post_init__(self) -> None: @classmethod def load(cls, fname: StrPath) -> Self: + """Load stack specification from given TOML file""" + stack_spec_path = as_normalized_path(fname) with open(stack_spec_path, "rb") as f: data = tomllib.load(f) @@ -1753,6 +1789,8 @@ def define_build_environment( build_dir: StrPath = "", index_config: PackageIndexConfig | None = None, ) -> "BuildEnvironment": + """Define layer build environments for this specification""" + build_path = self.resolve_lexical_path(build_dir) if index_config is None: index_config = PackageIndexConfig() @@ -1786,6 +1824,8 @@ def define_build_environment( @dataclass class BuildEnvironment: + """Interface to build specified layered environment stacks""" + METADATA_DIR = "__venvstacks__" # Output subdirectory for the build metadata METADATA_MANIFEST = "venvstacks.json" # File with full metadata for this build METADATA_ENV_DIR = ( @@ -2036,6 +2076,8 @@ def lock_exists(spec: _PythonEnvironmentSpec) -> bool: return not all(lock_exists(env.env_spec) for env in self.environments_to_lock()) def lock_environments(self, *, clean: bool = False) -> Sequence[EnvironmentLock]: + """Lock build environments for specified layers""" + # Lock environments without fully building them # Necessarily creates the runtime environments and # installs any declared build dependencies @@ -2045,6 +2087,8 @@ def lock_environments(self, *, clean: bool = False) -> Sequence[EnvironmentLock] return [env.lock_requirements() for env in self.environments_to_lock()] def create_environments(self, *, clean: bool = False, lock: bool = False) -> None: + """Create build environments for specified layers""" + # Base runtime environments need to exist before dependencies can be locked self.build_path.mkdir(parents=True, exist_ok=True) clean_runtime_envs = clean @@ -2079,6 +2123,8 @@ def _load_env_metadata( def load_archive_metadata( self, env_metadata_dir: Path, env: _PythonEnvironment, platform_tag: str = "" ) -> ArchiveMetadata | None: + """Load previously published archive metadata""" + # mypy is right to complain that the JSON hasn't been validated to conform # to the ArchiveMetadata interface, but we're OK with letting the runtime # errors happen in that scenario. Longer term, explicit JSON schemas should be @@ -2089,6 +2135,8 @@ def load_archive_metadata( def load_export_metadata( self, env_metadata_dir: Path, env: _PythonEnvironment ) -> ExportMetadata | None: + """Load previously exported environment metadata""" + # mypy is right to complain that the JSON hasn't been validated to conform # to the ExportMetadata interface, but we're OK with letting the runtime # errors happen in that scenario. Longer term, explicit JSON schemas should be @@ -2122,6 +2170,8 @@ def publish_artifacts( tag_outputs: bool = False, dry_run: bool = False, ) -> PublishedArchivePaths | tuple[Path, StackPublishingRequest]: + """Publish metadata and archives for specified layers""" + layer_data: dict[ LayerCategories, list[ArchiveMetadata | ArchiveBuildMetadata] ] = { @@ -2169,12 +2219,12 @@ def publish_artifacts( archive_paths.append(archive_path) result_data[env.category].append(build_metadata) manifest_data: StackPublishingResult = {"layers": result_data} - manifest_path, snippet_paths = self.write_artifacts_manifest( + manifest_path, snippet_paths = self._write_artifacts_manifest( metadata_dir, manifest_data, platform_tag ) return PublishedArchivePaths(manifest_path, snippet_paths, archive_paths) - def write_archive_metadata( + def _write_archive_metadata( self, env_metadata_dir: StrPath, archive_metadata: ArchiveMetadata, @@ -2187,7 +2237,7 @@ def write_archive_metadata( _write_json(metadata_path, archive_metadata) return metadata_path - def write_artifacts_manifest( + def _write_artifacts_manifest( self, metadata_dir: StrPath, manifest_data: StackPublishingResult, @@ -2216,7 +2266,7 @@ def write_artifacts_manifest( ): for env in layer_metadata[category]: snippet_paths.append( - self.write_archive_metadata(env_metadata_dir, env, platform_tag) + self._write_archive_metadata(env_metadata_dir, env, platform_tag) ) return manifest_path, snippet_paths @@ -2243,6 +2293,8 @@ def export_environments( force: bool = False, dry_run: bool = False, ) -> ExportedEnvironmentPaths | tuple[Path, StackExportRequest]: + """Locally export environments for specified layers""" + export_data: dict[LayerCategories, list[ExportMetadata]] = { RuntimeEnv.category: [], FrameworkEnv.category: [], @@ -2278,12 +2330,12 @@ def export_environments( export_paths.append(export_path) export_data[env.category].append(export_metadata) manifest_data: StackExportRequest = {"layers": export_data} - manifest_path, snippet_paths = self.write_export_manifest( + manifest_path, snippet_paths = self._write_export_manifest( metadata_dir, manifest_data ) return ExportedEnvironmentPaths(manifest_path, snippet_paths, export_paths) - def write_env_metadata( + def _write_env_metadata( self, env_metadata_dir: StrPath, env_metadata: ExportMetadata, @@ -2296,7 +2348,7 @@ def write_env_metadata( _write_json(metadata_path, env_metadata) return metadata_path - def write_export_manifest( + def _write_export_manifest( self, metadata_dir: StrPath, manifest_data: StackExportRequest ) -> tuple[Path, list[Path]]: formatted_manifest = _format_json(manifest_data) @@ -2317,5 +2369,5 @@ def write_export_manifest( LayerCategories.APPLICATIONS, ): for env in env_metadata[category]: - snippet_paths.append(self.write_env_metadata(env_metadata_dir, env)) + snippet_paths.append(self._write_env_metadata(env_metadata_dir, env)) return manifest_path, snippet_paths diff --git a/tox.ini b/tox.ini index f3c42cc..4fdbf76 100644 --- a/tox.ini +++ b/tox.ini @@ -58,13 +58,6 @@ allowlist_externals = sphinx-build commands = sphinx-build -b linkcheck {posargs} docs/ docs/_build -[testenv:regen-api-docs] -groups = [] -deps = -r docs/requirements.txt -allowlist_externals = docs/regen-api-docs.sh -commands = - docs/regen-api-docs.sh - [gh] python = 3.11 = py3.11