docs: Add workflow for documentation (#96)

.github/workflows/main.yaml

@@ -75,7 +75,9 @@ jobs:
         miniforge-variant: Mambaforge
 
     - name: Install dependencies
-      run: poetry install
+      run: |
+        poetry config virtualenvs.create false
+        poetry install
 
     - name: Run style checks
       run: makim tests.linter

.github/workflows/release.yaml

@@ -35,7 +35,9 @@ jobs:
           miniforge-variant: Mambaforge
 
       - name: Install deps
-        run: poetry install
+        run: |
+          poetry config virtualenvs.create false
+          poetry install
 
       - name: Run semantic release (for tests)
         if: ${{ github.event_name != 'workflow_dispatch' }}
@@ -67,4 +69,13 @@ jobs:
           -p "@google/semantic-release-replace-plugin" \
           semantic-release --ci
 
-    
+        # added for documentation
+      - name: Generate documentation with changes from semantic-release
+        run: makim docs.build
+
+      - name: GitHub Pages action
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build

conda/dev.yaml

@@ -5,4 +5,4 @@ channels:
 dependencies:
   - pip
   - python 3.8.1
-  - poetry >=1.7
+  - poetry 1.5.1

conda/release.yaml

@@ -4,5 +4,5 @@ channels:
   - conda-forge
 dependencies:
   - python 3.10.*  # min version supported
-  - poetry >=1.7
+  - poetry 1.5.1
   - nodejs >=18.17  # used by semantic-release

makim.yaml

@@ -0,0 +1,186 @@
+version: 1.0.0
+shell: bash
+groups:
+  clean:
+    env-file: .env
+    targets:
+      all:
+        help: Remove build artifacts, compiled files, and cache
+        run: |
+          rm -fr build/
+          rm -fr dist/
+          rm -fr .eggs/
+          find . -name '*.egg-info' -exec rm -fr {} +
+          find . -name '*.egg' -exec rm -f {} +
+          find . -name '*.pyc' -exec rm -f {} +
+          find . -name '__pycache__' -exec rm -fr {} +
+          find . -name '*~' -exec rm -f {} +
+          rm -f .coverage
+          rm -fr htmlcov/
+          rm -fr .pytest_cache
+
+  docs:
+    help: Commands for building and previewing the documentation
+    targets:
+      build:
+        help: Build the documentation
+        run: mkdocs build --config-file docs/mkdocs.yaml
+
+      preview:
+        help: Preview the documentation
+        dependencies:
+          - target: docs-build
+        run: mkdocs serve --watch docs --config-file docs/mkdocs.yaml
+
+  package:
+    help: helper commands for handling the package
+    targets:
+      build:
+        help: Build the project
+        run: poetry build
+
+  tests:
+    help: Test commands
+    targets:
+      linter:
+        help: Run lint checks
+        run: |
+          pre-commit install
+          pre-commit run --all-files --verbose
+
+      unit:
+        help: Run tests
+        args:
+          params:
+            help: Extra parameters for pytest
+            type: str
+            default: "-vv"
+        run: pytest -s {{ args.params }} tests
+
+      smoke-1:
+        help: Run smoke tests for group 1
+        dependencies:
+          - target: docker.killall
+        run: |
+          sugar build --verbose
+          sugar build --verbose --group group1 --all
+          sugar build --verbose --group group1
+          sugar build --verbose --group group1 --services service1-1
+          sugar pull --verbose --group group1 --all
+          sugar pull --verbose --group group1
+          sugar pull --verbose --group group1 --services service1-1
+          sugar ext start --verbose --group group1 --all --options -d
+          sugar ext restart --verbose --group group1 --all --options -d
+          sugar exec --verbose --group group1 --service service1-1 --options -T --cmd env
+          sugar stop --verbose --group group1 --all
+          sugar run --verbose --group group1 --service service1-1 --options -T --cmd env
+          sugar down --verbose --group group1
+
+      smoke-2:
+        help: Run smoke tests for group 2
+        dependencies:
+          - target: docker.killall
+        run: |
+          sugar build --verbose --group group2 --all
+          sugar build --verbose --group group2
+          sugar build --verbose --group group2 --services service2-1
+          sugar pull --verbose --group group2 --all
+          sugar pull --verbose --group group2
+          sugar pull --verbose --group group2 --services service2-1
+          sugar ext start --verbose --group group2 --all --options -d
+          sugar ext restart --verbose --group group2 --all --options -d
+          sugar exec --verbose --group group2 --service service2-1 --options -T --cmd env
+          sugar stop --verbose --group group2 --all
+          sugar run --verbose --group group2 --service service2-1 --options -T --cmd env
+          sugar down --verbose --group group2
+
+      smoke-mix:
+        help: Run smoke tests for group mix
+        dependencies:
+          - target: docker.killall
+        run: |
+          sugar build --verbose --group group-mix --all
+          sugar build --verbose --group group-mix
+          sugar build --verbose --group group-mix --services service1-1,service2-1
+          sugar pull --verbose --group group-mix --all
+          sugar pull --verbose --group group-mix
+          sugar pull --verbose --group group-mix --services service1-1,service2-1
+          sugar ext start --verbose --group group-mix --all --options -d
+          sugar ext restart --verbose --group group-mix --all --options -d
+          sugar exec --verbose --group group-mix --service service2-1 --options -T --cmd env
+          sugar stop --verbose --group group-mix --all
+          sugar run --verbose --group group-mix --service service2-1 --options -T --cmd env
+          sugar down --verbose --group group-mix
+
+      smoke-main:
+        help: Run smoke tests for group main
+        dependencies:
+          - target: docker.killall
+        run: |
+          # general tests main profile/plugins
+          sugar build --verbose --group group1
+          sugar config --verbose --group group1
+          sugar create --verbose --group group1
+          sugar ext start --verbose --group group1 --options -d
+          sugar ext restart --verbose --group group1 --options -d
+          sugar exec --verbose --group group1 --service service1-1 --options -T --cmd env
+          sugar images --verbose --group group1
+          sugar logs --verbose --group group1
+          # port is not complete supported
+          # sugar port --verbose --group group1 --service service1-1
+          sugar ps --verbose --group group1
+          sugar pull --verbose --group group1
+          sugar push --verbose --group group1
+          sugar run --verbose --group group1 --service service1-1 --options -T --cmd env
+          sugar top --verbose --group group1
+          sugar up --verbose --group group1 --options -d
+          sugar version --verbose
+          # port is not complete supported
+          # sugar events --verbose --group group1 --service service1-1 --options --json --dry-run
+
+      smoke-defaults:
+        help: Run smoke tests for group defaults
+        dependencies:
+          - target: docker.killall
+        run: |
+          export KXGR_PROJECT_NAME="test-`python -c 'from uuid import uuid4; print(uuid4().hex[:7])'`"
+          echo $KXGR_PROJECT_NAME
+          sugar build --verbose --group group-defaults
+          sugar ext start --verbose --group group-defaults --options -d
+          sugar ext restart --verbose --group group-defaults --options -d
+          docker ps|grep $KXGR_PROJECT_NAME
+          sugar ext stop --verbose --group group-defaults
+
+      smoke-final:
+        help: Run final smoke tests
+        dependencies:
+          - target: docker.killall
+        run: |
+          sugar ext restart --verbose --group group-defaults --options -d
+          sugar pause --verbose --group group1
+          sugar unpause --verbose --group group1
+          sugar kill --verbose --group group1
+          sugar stop --verbose --group group1
+          sugar rm --verbose --group group1 --options --force
+          sugar down --verbose --group group1
+
+      smoke:
+        help: Run final smoke tests
+        dependencies:
+          - target: docker.killall
+          - target: tests.smoke-1
+          - target: tests.smoke-2
+          - target: tests.smoke-mix
+          - target: tests.smoke-main
+          - target: tests.smoke-defaults
+          - target: tests.smoke-final
+        run: |
+          sugar --help
+          sugar --version
+
+  docker:
+    help: Commands for docker
+    targets:
+      killall:
+        help: Kill all running Docker containers
+        run: docker kill `docker ps -q` || true

mkdocs.yaml

@@ -0,0 +1,151 @@
+site_name: ContainersSugar
+site_url: https://osl-incubator.github.io/containers-sugar
+repo_url: https://github.com/osl-incubator/containers-sugar
+docs_dir: ./docs
+site_dir: ./build
+# extra_css:
+#   - stylesheets/extra.css
+# Page tree
+nav:
+  - index.md
+  - Installation: installation.md
+  - Changelog: changelog.md
+  - Contributing: contributing.md
+#  - API: api/references.md
+  - Notebook page: example.ipynb
+theme:
+  name: material
+  features:
+    - content.code.annotate
+    - content.tabs.link
+    - header.autohide
+    - navigation.indexes
+    - navigation.instant
+    - search.highlight
+    - search.share
+    - search.suggest
+  icon:
+    repo: fontawesome/brands/github
+  logo: images/logo.png
+  favicon: images/favicon.ico
+  palette:
+    scheme: slate
+    primary: white
+    accent: lime
+  # custom_dir: docs/overrides
+plugins:
+  - search
+  - macros
+  # - autorefs
+  # - exclude:
+  #     glob:
+  #       - backends/template.md
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          paths: [../src]
+
+          import:
+            - https://docs.python.org/3/objects.inv
+          options:
+            docstring_style: numpy
+            filters:
+              - "!^Bounds"
+              - "!^__class__"
+              - "!^_filter_with_like"
+              - "!^_find_backends"
+              - "!^_key$"
+              - "!^_literal_value_hash_key"
+              - "!^_log"
+              - "!^_nbytes"
+              - "!^_safe_name$"
+              - "!^_schema_from_csv"
+              - "!^_to_geodataframe"
+              - "!^_tuplize"
+              - "!^ast_schema"
+              - "!^backend_table_type"
+              - "!^bounds$"
+              - "!^column$"
+              - "!^compiler$"
+              - "!^context_class"
+              - "!^database_class"
+              - "!^do_connect"
+              - "!^fetch_from_cursor"
+              - "!^get_schema"
+              - "!^largest$"
+              - "!^reconnect"
+              - "!^select_builder_class"
+              - "!^select_class"
+              - "!^table_class$"
+              - "!^table_expr_class"
+              - "!^translator_class"
+              - "!^Options$"
+            show_category_heading: true
+            show_root_full_path: false
+            show_root_heading: true
+            show_root_toc_entry: true
+            show_source: false
+            show_modules: true
+  - mkdocs-jupyter:
+      execute: false
+      ignore:
+        - "*.py"
+      # execute_ignore: "tutorial/*Geospatial*.ipynb"
+      include_source: true
+      theme: dark
+  - literate-nav
+markdown_extensions:
+  - admonition
+  - attr_list
+  - codehilite
+  - def_list
+  - footnotes
+  - md_in_html
+  - meta
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+      options:
+        custom_icons:
+          - docs/static/icons
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink:
+      provider: github
+      repo_url_shortener: true
+  - pymdownx.saneheaders
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - toc
+extra:
+  project_name: "Containers-Sugar"
+  team:
+    - name: "Active maintainers"
+      members:
+        - xmnlab
+        - joel5vega
+    - name: "Former maintainers"
+      members:
+        - xmnlab
+  social:
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/xmnlab
+    - icon: fontawesome/brands/github
+      link: https://github.com/osl-incubator/containers-sugar
+  support_levels:
+    supported:
+      icon: :material-check-decagram:{ .verified }
+      description: Tested in CI. If this doesn't work for you, please [file an issue](https://github.com/arxlang/astx/issues/new).
+    bug:
+      icon: :material-bug:{ .bug }
+      description: Should work but doesn't because upstream is broken. Supported on a best-effort basis.
+    unsupported:
+      icon: :material-cancel:{ .cancel }
+      description: Unlikely to ever be supported or no upstream support.
+
+copyright: "Copyright © 2023, Contaner-sugar Team"