From 8dc324ef6f80645bb721dfbde6eccfe1fae498c2 Mon Sep 17 00:00:00 2001 From: julesbertrand Date: Wed, 11 Dec 2024 16:47:41 +0100 Subject: [PATCH 1/3] docs: add api ref using mkdocstrings --- deployer/pipeline_checks.py | 2 +- docs/{ => advanced}/advanced_user_guide.md | 0 docs/{ => advanced}/configuration.md | 0 docs/api/pipeline_checks.md | 11 +++++++++ docs/api/utils.md | 26 ++++++++++++++++++++++ docs/api/vertex_deployer.md | 6 +++++ mkdocs.yml | 22 ++++++++++++++++-- pyproject.toml | 1 + 8 files changed, 65 insertions(+), 3 deletions(-) rename docs/{ => advanced}/advanced_user_guide.md (100%) rename docs/{ => advanced}/configuration.md (100%) create mode 100644 docs/api/pipeline_checks.md create mode 100644 docs/api/utils.md create mode 100644 docs/api/vertex_deployer.md diff --git a/deployer/pipeline_checks.py b/deployer/pipeline_checks.py index 60d693d..4bb3364 100644 --- a/deployer/pipeline_checks.py +++ b/deployer/pipeline_checks.py @@ -146,7 +146,7 @@ def _convert_artifact_type_to_str(annotation: type) -> type: """Convert a kfp.dsl.Artifact type to a string. This is mandatory for type checking, as kfp.dsl.Artifact types should be passed as strings - to VertexAI. See https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.PipelineJob + to VertexAI. See `https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.PipelineJob` for details. """ if isinstance(annotation, _AnnotatedAlias): diff --git a/docs/advanced_user_guide.md b/docs/advanced/advanced_user_guide.md similarity index 100% rename from docs/advanced_user_guide.md rename to docs/advanced/advanced_user_guide.md diff --git a/docs/configuration.md b/docs/advanced/configuration.md similarity index 100% rename from docs/configuration.md rename to docs/advanced/configuration.md diff --git a/docs/api/pipeline_checks.md b/docs/api/pipeline_checks.md new file mode 100644 index 0000000..4b6d160 --- /dev/null +++ b/docs/api/pipeline_checks.md @@ -0,0 +1,11 @@ +::: deployer.pipeline_checks + options: + allow_inspection: false + merge_init_into_class: false + group_by_category: false + members: + - Pipelines + - Pipeline + - ConfigsDynamicModel + - ConfigDynamicModel + - _convert_artifact_type_to_str diff --git a/docs/api/utils.md b/docs/api/utils.md new file mode 100644 index 0000000..0116872 --- /dev/null +++ b/docs/api/utils.md @@ -0,0 +1,26 @@ +::: deployer.utils.models + options: + show_root_heading: true + members: + - create_model_from_func + +::: deployer.utils.utils + options: + show_root_heading: true + members: + - make_enum_from_python_package_dir + - import_pipeline_from_dir + +::: deployer.utils.config + options: + show_root_heading: true + merge_init_into_class: false + allow_inspection: true + members: + - VertexPipelinesSettings + - load_vertex_settings + - list_config_filepaths + - load_config + - _load_config_python + - _load_config_yaml + - _load_config_toml diff --git a/docs/api/vertex_deployer.md b/docs/api/vertex_deployer.md new file mode 100644 index 0000000..1c9af78 --- /dev/null +++ b/docs/api/vertex_deployer.md @@ -0,0 +1,6 @@ +::: deployer.pipeline_deployer.VertexPipelineDeployer + options: + show_root_heading: true + allow_inspection: true + merge_init_into_class: false + group_by_category: false diff --git a/mkdocs.yml b/mkdocs.yml index 9dd8bb4..9643044 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,20 @@ theme: plugins: - search + - mkdocstrings: + handlers: + python: + paths: [.] + options: + members_order: source + separate_signature: true + filters: ["!^_"] + docstring_options: + ignore_init_summary: true + merge_init_into_class: true + show_signature_annotations: true + signature_crossrefs: true + show_symbol_type_heading: true markdown_extensions: - admonition @@ -81,8 +95,12 @@ nav: - Folder Structure: folder_structure.md - Basic Usage: usage.md - Advanced User Guide: - - Vertex DevOps: advanced_user_guide.md - - Understand settings and configurations: configuration.md + - Vertex DevOps: advanced/advanced_user_guide.md + - Understand settings and configurations: advanced/configuration.md - CLI Reference: CLI_REFERENCE.md + - API Documentation: + - VertexPipelinesDeployer: api/vertex_deployer.md + - pipeline_checks: api/pipeline_checks.md + - utils: api/utils.md - Contributing: contributing.md - Changelog: changelog.md diff --git a/pyproject.toml b/pyproject.toml index feae642..142c967 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,6 +49,7 @@ codespell = "^2.2" [tool.poetry.group.docs.dependencies] mkdocs = "^1.5" mkdocs-material = {extras = ["pygments"], version = "^9.5.17"} +mkdocstrings = "^0.26" [tool.poetry.extras] profiling = ["pyinstrument"] From d40315cfd3291399c5682dab189a819503b37808 Mon Sep 17 00:00:00 2001 From: julesbertrand Date: Wed, 11 Dec 2024 17:18:58 +0100 Subject: [PATCH 2/3] docs: typo --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 9643044..38b60c0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -99,7 +99,7 @@ nav: - Understand settings and configurations: advanced/configuration.md - CLI Reference: CLI_REFERENCE.md - API Documentation: - - VertexPipelinesDeployer: api/vertex_deployer.md + - VertexPipelineDeployer: api/vertex_deployer.md - pipeline_checks: api/pipeline_checks.md - utils: api/utils.md - Contributing: contributing.md From f1492fdaa7ad778c64412bed46438b44f34a3788 Mon Sep 17 00:00:00 2001 From: julesbertrand Date: Wed, 11 Dec 2024 17:39:16 +0100 Subject: [PATCH 3/3] docs: typo url --- deployer/pipeline_checks.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deployer/pipeline_checks.py b/deployer/pipeline_checks.py index 4bb3364..9d14692 100644 --- a/deployer/pipeline_checks.py +++ b/deployer/pipeline_checks.py @@ -146,7 +146,7 @@ def _convert_artifact_type_to_str(annotation: type) -> type: """Convert a kfp.dsl.Artifact type to a string. This is mandatory for type checking, as kfp.dsl.Artifact types should be passed as strings - to VertexAI. See `https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.PipelineJob` + to VertexAI. See for details. """ if isinstance(annotation, _AnnotatedAlias):