Docs support

.github/workflows/docs.yaml

@@ -0,0 +1,24 @@
+name: docs
+on:
+  push:
+    branches:
+      - docs-support
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material
+      - run: pip install pillow cairosvg
+      - run: python ./pre_docs.py
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -12,3 +12,8 @@ __pycache__/
 # Editors
 .idea/
 *.iml
+
+# docs
+site
+.cache
+docs/

3rdparty/BUILD

@@ -15,8 +15,15 @@ python_requirement(
     modules=["pydantic", "pydantic_core", "pydantic_settings"],
 )
 python_requirement(
-    name="pydantic_v2",
-    requirements=["pydantic==2.1.1", "pydantic-settings==2.0.3"],
+    name="pydantic_v2_settings",
+    requirements=["pydantic-settings>=2.0.3"],
     resolve="python-default",
-    modules=["pydantic", "pydantic_core", "pydantic_settings"],
+    modules=["pydantic_settings"],
+)
+
+python_requirement(
+    name="pydantic_v1_or_later",
+    requirements=["pydantic>=1.10.2,<3"],
+    resolve="python-default",
+    modules=["pydantic", "pydantic_core"],
 )

_pants/3rdparty/lock.txt

@@ -10,16 +10,16 @@
 //   ],
 //   "generated_with_requirements": [
 //     "PyYAML==6.0.1",
-//     "compose-chart-export==0.0.24",
-//     "docker-compose-parser==0.0.24",
-//     "model-lib==0.0.24",
+//     "compose-chart-export==0.0.27",
+//     "docker-compose-parser==0.0.27",
+//     "model-lib==0.0.27",
 //     "orjson==3.6.5",
 //     "pantsbuild.pants.testutil<2.17,>=2.16.0a0",
 //     "pantsbuild.pants<2.17,>=2.16.0a0",
 //     "pydantic==1.10.2",
 //     "pydevd-pycharm==231.8109.197",
 //     "typing_extensions>=4.3.0",
-//     "zero-3rdparty==0.0.24"
+//     "zero-3rdparty==0.0.27"
 //   ],
 //   "manylinux": "manylinux2014",
 //   "requirement_constraints": [],
@@ -218,38 +218,44 @@
           "artifacts": [
             {
               "algorithm": "sha256",
-              "hash": "e2b24bb985fccc0c2d7e4bf4472f338aeb4a34dc42886a3e4c85849f582c2c54",
-              "url": "https://files.pythonhosted.org/packages/bd/ba/e5372e4008221fb063a05fa687dd61d9112e4f60491afe69e8aaded0da41/compose_chart_export-0.0.24-py3-none-any.whl"
+              "hash": "26179a0d9736279845e024f2ffe129d4c1ca257adeb297ae568d4e0d1b12457b",
+              "url": "https://files.pythonhosted.org/packages/21/87/7ff6a874be293823cd9efafb481096eec2796d2ae0f636b44e5b2ee7034d/compose_chart_export-0.0.27-py3-none-any.whl"
             }
           ],
           "project_name": "compose-chart-export",
           "requires_dists": [
-            "docker-compose-parser==0.0.24",
-            "model-lib==0.0.24",
-            "pydantic==1.10.2",
+            "docker-compose-parser==0.0.27",
+            "model-lib==0.0.27",
+            "pydantic-settings>=2.0.3; extra == \"pydantic_v2\"",
+            "pydantic<3,>=1.10.2",
+            "pydantic<=2,>=1.10.2; extra == \"pydantic_v1\"",
+            "pydantic<=3,>=2.1.1; extra == \"pydantic_v2\"",
             "semver==2.13.0",
             "typing-extensions>=4.3.0",
-            "zero-3rdparty==0.0.24"
+            "zero-3rdparty==0.0.27"
           ],
           "requires_python": ">=3.9",
-          "version": "0.0.24"
+          "version": "0.0.27"
         },
         {
           "artifacts": [
             {
               "algorithm": "sha256",
-              "hash": "86688c1a4ceeae1977a1d2110d43aa00a24c2de95e7aab92105643d65df1fcd0",
-              "url": "https://files.pythonhosted.org/packages/24/a2/644207ea37eb29bdb5d6e52eb17b21452dbac336d0f9b3c13b1cf7c972e9/docker_compose_parser-0.0.24-py3-none-any.whl"
+              "hash": "c81f3f217e67b668278ffceb71207acee28b006a54bb4c5b3e5af13d6c5eb5d2",
+              "url": "https://files.pythonhosted.org/packages/7a/13/b33fa8e7d79223ffadb4ec6ad58d297b59d56339ab7c1fd48118b46bc334/docker_compose_parser-0.0.27-py3-none-any.whl"
             }
           ],
           "project_name": "docker-compose-parser",
           "requires_dists": [
-            "model-lib==0.0.24",
-            "pydantic==1.10.2",
-            "zero-3rdparty==0.0.24"
+            "model-lib==0.0.27",
+            "pydantic-settings>=2.0.3; extra == \"pydantic_v2\"",
+            "pydantic<3,>=1.10.2",
+            "pydantic<=2,>=1.10.2; extra == \"pydantic_v1\"",
+            "pydantic<=3,>=2.1.1; extra == \"pydantic_v2\"",
+            "zero-3rdparty==0.0.27"
           ],
           "requires_python": ">=3.9",
-          "version": "0.0.24"
+          "version": "0.0.27"
         },
         {
           "artifacts": [
@@ -415,20 +421,23 @@
           "artifacts": [
             {
               "algorithm": "sha256",
-              "hash": "de5d5cc875adcacf36e5ff738b01119d261f4c2766d0d03e8a9782cd214d7963",
-              "url": "https://files.pythonhosted.org/packages/05/e1/de1649bb8281cef96aaf78954b19402765b176dbfd1c26fa0cf9352a0c59/model_lib-0.0.24-py3-none-any.whl"
+              "hash": "e13d4a56eab00da2abd9d041faffbaee43977ba99befc454e98497c88a756903",
+              "url": "https://files.pythonhosted.org/packages/c8/9d/550f403267f7121c6b1bc90ff520f86c7c51876b4c4944b1a64533edb595/model_lib-0.0.27-py3-none-any.whl"
             }
           ],
           "project_name": "model-lib",
           "requires_dists": [
             "PyYAML==6.0.1",
             "orjson>=3.6.5; extra == \"json\"",
-            "pydantic==1.10.2",
+            "pydantic-settings>=2.0.3; extra == \"pydantic_v2\"",
+            "pydantic<3,>=1.10.2",
+            "pydantic<=2,>=1.10.2; extra == \"pydantic_v1\"",
+            "pydantic<=3,>=2.1.1; extra == \"pydantic_v2\"",
             "typing-extensions>=4.3.0",
-            "zero-3rdparty==0.0.24"
+            "zero-3rdparty==0.0.27"
           ],
           "requires_python": ">=3.9",
-          "version": "0.0.24"
+          "version": "0.0.27"
         },
         {
           "artifacts": [
@@ -1252,16 +1261,19 @@
           "artifacts": [
             {
               "algorithm": "sha256",
-              "hash": "236dd629af46d62fdf6d9fe8e94030b00efd01cbf71d006290daf92ca63faeee",
-              "url": "https://files.pythonhosted.org/packages/8f/ed/b2555355fed9fdc5c9630ec061f1c9ead152134dda37ee5c5d60a537cf59/zero_3rdparty-0.0.24-py3-none-any.whl"
+              "hash": "5487b1320b06fd5453c9137563f6058830f4bfb0f7d6154aa95b09395ad4aafb",
+              "url": "https://files.pythonhosted.org/packages/08/31/9c7bee6f639423f16094fe69d06645d55acc26cc4054d615bfbd0948fbd8/zero_3rdparty-0.0.27-py3-none-any.whl"
             }
           ],
           "project_name": "zero-3rdparty",
           "requires_dists": [
+            "pydantic-settings>=2.0.3; extra == \"pydantic_v2\"",
+            "pydantic<=2,>=1.10.2; extra == \"pydantic_v1\"",
+            "pydantic<=3,>=2.1.1; extra == \"pydantic_v2\"",
             "typing-extensions>=4.3.0"
           ],
           "requires_python": ">=3.9",
-          "version": "0.0.24"
+          "version": "0.0.27"
         }
       ],
       "platform_tag": null
@@ -1273,16 +1285,16 @@
   "prefer_older_binary": false,
   "requirements": [
     "PyYAML==6.0.1",
-    "compose-chart-export==0.0.24",
-    "docker-compose-parser==0.0.24",
-    "model-lib==0.0.24",
+    "compose-chart-export==0.0.27",
+    "docker-compose-parser==0.0.27",
+    "model-lib==0.0.27",
     "orjson==3.6.5",
     "pantsbuild.pants.testutil<2.17,>=2.16.0a0",
     "pantsbuild.pants<2.17,>=2.16.0a0",
     "pydantic==1.10.2",
     "pydevd-pycharm==231.8109.197",
     "typing_extensions>=4.3.0",
-    "zero-3rdparty==0.0.24"
+    "zero-3rdparty==0.0.27"
   ],
   "requires_python": [
     "<3.10,>=3.9"

_pants/3rdparty/requirements.txt

@@ -2,7 +2,7 @@ PyYAML==6.0.1
 pydantic==1.10.2
 typing_extensions>=4.3.0
 orjson==3.6.5
-model-lib==0.0.24
-docker-compose-parser==0.0.24
-compose-chart-export==0.0.24
-zero-3rdparty==0.0.24
+model-lib==0.0.27
+docker-compose-parser==0.0.27
+compose-chart-export==0.0.27
+zero-3rdparty==0.0.27

_pants/pants_py_deploy/src/pants_py_deploy/BUILD

@@ -5,7 +5,7 @@ python_distribution(
     long_description_path="_pants/pants_py_deploy/readme.md",
     provides=setup_py(
         name="pants-py-deploy",
-        version="0.0.24",
+        version=VERSION,
         description="Make it easy to maintain docker-compose files and helm-charts across projects with pants-py-deploy",
         author="Espen Albert",
         classifiers=[

_pants/py_package.py

@@ -1,3 +1,4 @@
+VERSION = "0.0.27"
 def py_package(
     *,
     description: str,
@@ -11,7 +12,7 @@ def py_package(
     extra_dependencies = extra_dependencies or []
     all_dependencies = [
         f":{folder_name}@resolve={resolve}",
-        f"!!//3rdparty:pydantic_v2",
+        "!!//3rdparty:pydantic_v2_settings", # settings are optional
     ] + extra_dependencies
     resources(name="py-typed", sources=["py.typed"])
     python_sources(sources=["*.py"], dependencies=[":py-typed"])
@@ -31,7 +32,7 @@ def py_package(
         long_description_path=f"{folder_name}/readme.md",
         provides=setup_py(
             name=distribution_name,
-            version="0.0.24",
+            version=VERSION,
             description=description,
             author="Espen Albert",
             classifiers=[
@@ -41,9 +42,12 @@ def py_package(
             extras_require=extras_require or {},
             long_description_content_type="text/markdown",
             license="MIT",
-            url="https://github.com/EspenAlbert/py-libs",
+            project_urls={
+                "Source": f"https://github.com/EspenAlbert/py-libs/tree/main/{folder_name}",
+                "Documentation": f'https://espenalbert.github.io/py-libs/{folder_name}',
+            }
         ),
         wheel=True,
         sdist=False,
         repositories=["@pypi"],
-    )
+    )

docker_compose_parser/src/docker_compose_parser/file_models.py

@@ -45,8 +45,9 @@
         @field_validator("default_env", mode="before")
         def parse_list(cls, value):
             if isinstance(value, list):
-                return key_equal_value_to_dict(value)
-            return value
+                value = key_equal_value_to_dict(value)
+            # pydantic v2 will not "convert" values to strings
+            return {k: str(v) for k, v in value.items()}
 
     else:
         from pydantic import validator  # type: ignore

mkdocs.yml

@@ -0,0 +1,65 @@
+site_name: py-libs documentation
+site_url: https://espenalbert.github.io/py-libs/
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+      primary: teal
+      accent: purple
+    - scheme: slate
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+      primary: teal
+      accent: lime
+
+plugins:
+  - social
+  - search
+
+repo_name: EspenAlbert/py-libs
+repo_url: https://github.com/EspenAlbert/py-libs
+edit_uri: edit/main/docs/
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/EspenAlbert
+
+nav:
+- Get Started: index.md
+- Model Lib: model_lib
+- Compose Chart Export: compose_chart_export
+- Docker Compose Parser: docker_compose_parser
+- zero-3rdparty: zero_3rdparty
+
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg

pants.toml

@@ -43,7 +43,7 @@ enable_resolves = true
 
 [python.resolves]
 pants-plugins = "_pants/3rdparty/lock.txt"
-pydantic-v1 = "_pants/3rdparty/pydantic-v1"
+pydantic-v1 = "3rdparty/python/pydantic-v1.lock"
 python-default = "3rdparty/python/default.lock"
 
 [python.resolves_to_interpreter_constraints]
@@ -104,5 +104,5 @@ linux_amd = "//:linux_amd"
 linux_arm = "//:linux_arm"
 
 [tailor]
-ignore_adding_targets=["_pants:_pants"]
+ignore_adding_targets=["_pants:_pants", "//:root"]
 ignore_paths=["compose_chart_export/tests/test_chart_export/charts/**"]

pre_docs.py

@@ -0,0 +1,34 @@
+import shutil
+from pathlib import Path
+from typing import Iterable
+
+SRC = Path(__file__).parent
+DOCS_DIR = SRC / "docs"
+IGNORED_MD_DIRECTORIES = [".pytest_cache", "test", "dist"]
+
+FILENAME_RENAME = {
+    "readme.md": "index.md"
+}
+
+def ignore_md_path(rel_path: str) -> bool:
+    return any(f"{d}/" in rel_path for d in IGNORED_MD_DIRECTORIES)
+
+
+def add_dest_paths(src_path: Path, md_dest_path: Path) -> Iterable[Path]:
+    if new_name := FILENAME_RENAME.get(md_dest_path.name):
+        yield md_dest_path.parent / new_name
+    yield md_dest_path
+
+def move_md_files():
+    for md_src_path in SRC.rglob("*.md"):
+        rel_path = str(md_src_path.relative_to(SRC))
+        if md_src_path.is_relative_to(DOCS_DIR) or ignore_md_path(rel_path):
+            continue
+        md_dest_path = DOCS_DIR / rel_path
+        for final_dest_path in add_dest_paths(md_src_path, md_dest_path):
+            final_dest_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy(md_src_path, final_dest_path)
+
+
+if __name__ == "__main__":
+    move_md_files()