0.4.0 release, clean up

.gitignore

@@ -6,3 +6,4 @@ htmlcov
 dist/
 docs/build
 .venv
+.DS_store

README.md

@@ -9,7 +9,7 @@ This repository contains two packages: [`kbatch`](./kbatch) is for users, [`kbat
 `kbatch` can be installed from source using pip:
 
 ```
-$ pip install "git+https://github.com/kbatch-dev/kbatch/#egg=kbatch&subdirectory=kbatch"
+$ pip install kbatch
 ```
 
 ## Usage
@@ -101,6 +101,23 @@ Show the detail on a given job
 $ kbatch job show "<job-id>
 ```
 
+### Submit cronjob 
+
+Similar to jobs, cronjobs require `name`, `command` and container `image`. However cronjobs also require a `schedule` which follows the [cron schedule syntax](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax).
+
+
+```{code-block} console
+$ kbatch cronjob submit \
+    --name=list-files \
+    --image=alpine \
+    --command='["ls", "-lh"]' \
+    --schedule='0 22 * * 1-5'
+```
+
+This job will now run at 22:00 on every day-of-week from Monday through Friday **indefinitely**.
+
+> NOTE: Given that cronjobs run on a schedule **indefinitely**, the only way to stop them is to manually delete the cronjob. See the [user guide docs](https://kbatch.readthedocs.io/en/latest/user-guide.html#submit-a-cronjob) for more information.
+
 ### Show pod logs
 
 Note that this is the **pod** id, not the **job** id.

docs/source/conf.py

@@ -22,7 +22,7 @@
 author = "Tom Augspurger"
 
 # The full version, including alpha/beta/rc tags
-release = "0.3.2"
+release = "0.4.0"
 
 
 # -- General configuration ---------------------------------------------------

docs/source/dev-guide.md

@@ -0,0 +1,113 @@
+# Dev Guide
+
+## Development setup
+
+Clone the `kbatch` repo onto your local machine and create a virtual environment (`conda`, `venv`, etc.) with Python 3.9 installed. From this directory, you can pip install the packages needed for development
+
+```
+$ pip install -e ./kbatch[all]
+...
+$ pip install -e ./kbatch-proxy[all]
+```
+
+> NOTE: The `-e` signifies that this is an "editable install", read more [here](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs).
+
+The first pip install command above should've also installed `pre-commit` which is used to format and lint the code. Run the following command to start using `pre-commit`
+
+```
+$ pre-commit install --install-hooks
+```
+
+### Run `pytest`
+
+To validate your changes against the test suite, run
+
+```
+$ pytest -v ./kbatch
+...
+$ pytest -v ./kbatch-proxy
+```
+
+### Run `mypy`
+
+To perform `mypy` type checking, run
+
+```
+$ mypy ./kbatch
+...
+$ mypy ./kbatch-proxy
+```
+
+### To build the docs locally
+
+To build the docs locally, run
+
+```
+$ cd ./docs
+$ make html
+```
+
+
+## `kbatch-proxy` development setup
+
+We don't have a fully working docker-ized setup, since we (i.e. Tom) don't know how to do Kubernetes within docker. So the current setup relies on
+
+1. k3d for Kubernetes
+2. JupyterHub as a regular Python process
+3. kbatch-proxy as a regular Python process
+
+### Create a cluster
+
+```
+$ k3d cluster create ksubmit
+```
+
+### Create a Hub
+
+make sure to `npm install configurable-http-proxy`.
+
+```
+$ cd hub
+$ jupyterhub
+```
+
+### Start kbatch-proxy
+
+```
+KBATCH_PREFIX=/services/kbatch \
+  KBATCH_PROFILE_FILE=tests/profile_template.yaml \
+  JUPYTERHUB_API_TOKEN=super-secret \
+  JUPYTERHUB_API_URL=http://127.0.0.1:8000/hub/api \
+  JUPYTERHUB_HOST=http://127.0.0.1:8000 \
+  uvicorn kbatch_proxy.main:app --reload --port=8050
+```
+
+You'll might want to log in and create a token at http://localhost:8000/hub/token. The `kbatch configure` with that token.
+
+## Release process
+
+These are the current steps that it takes to cut a new release of `kbatch`.
+
+### Release new version of `kbatch`/`kbatch-proxy`:
+1. Update the version in the following files:
+   - [`kbatch/setup.cfg`](https://github.com/kbatch-dev/kbatch/blob/main/kbatch/setup.cfg#L7)
+   - [`kbatch/kbatch/__init__.py`](https://github.com/kbatch-dev/kbatch/blob/main/kbatch/kbatch/__init__.py#L17)
+   - [`kbatch-proxy/setup.cfg`](https://github.com/kbatch-dev/kbatch/blob/main/kbatch-proxy/setup.cfg#L7)
+   - [`docs/source/conf.py`](https://github.com/kbatch-dev/kbatch/blob/main/docs/source/conf.py#L25)
+3. Update any relevant docs and merge these changes into the codebase. 
+2. [Draft a release on the `kbatch` GitHub repo.](https://github.com/kbatch-dev/kbatch/releases).
+   - This triggers the [`publish-image.yaml`](https://github.com/kbatch-dev/kbatch/blob/main/.github/workflows/publish-image.yaml) workflow which:
+     - publishes a container image for `kbatch-proxy` to the [GitHub container registry](https://github.com/kbatch-dev/kbatch/pkgs/container/kbatch-proxy).
+     - publish `kbatch` and `kbatch-proxy` python libraries to PyPI.
+
+
+### Release new version of `helm-chart`:
+1. Once the container image and libraries have been successfully published, update the version of the `helm-chart` to match this new version of `kbatch`:
+   - [`kbatch/Chart.yaml`](https://github.com/kbatch-dev/helm-chart/blob/main/kbatch/Chart.yaml#L6)
+2. Update any relevant docs and merge these changes into the codebase.
+3. [Draft a release on the `helm-chart` GitHub repo.](https://github.com/kbatch-dev/helm-chart/releases)
+   - This triggers the [`publish-chart.yaml`](https://github.com/kbatch-dev/helm-chart/blob/main/.github/workflows/publish-charts.yml) workflow which:
+     - publishes a Helm chart to the [GitHub Pages site](https://kbatch-dev.github.io/helm-chart/) for this repo.
+
+> NOTE: there are known limitations to the pre-release process outlined [here](https://github.com/kbatch-dev/kbatch/issues/42).
+

docs/source/index.md

@@ -59,4 +59,5 @@ For more on how to use `kbatch`, see the [User guide](./user-guide.md)
 user-guide
 examples/index.md
 kbatch-proxy
+dev-guide
 ```

docs/source/user-guide.md

@@ -59,7 +59,7 @@ If you'd like your job to run on a repeating schedule, you can leverage CronJobs
 $ kbatch cronjob submit \
     --name=list-files \
     --image=alpine \
-    --command='["ls", "-lh"]'
+    --command='["ls", "-lh"]' \
     --schedule='0 22 * * 1-5'
 ```
 

kbatch-proxy/setup.cfg

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [metadata]
 name = kbatch-proxy
-version = 0.3.2
+version = 0.4.0
 description = Proxy batch job requests to kubernetes.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -23,10 +23,18 @@ install_requires =
     pydantic[dotenv]
 
 [options.extras_require]
+all =
+    %(test)s
+    %(dev)s
 test =
     pytest
     pytest-mock
 
+dev = 
+    uvicorn[standard]
+    gunicorn==20.1.0
+    rich
+
 [options.entry_points]
 console_scripts =
     kbatch = kbatch.cli:cli

kbatch/kbatch/__init__.py

@@ -14,7 +14,7 @@
 from ._backend import make_job, make_cronjob
 
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",

kbatch/setup.cfg

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [metadata]
 name = kbatch
-version = 0.3.2
+version = 0.4.0
 description = Submit batch jobs to Kubernetes.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -22,9 +22,15 @@ install_requires =
     kubernetes
 
 [options.extras_require]
+all =
+    %(docs)s
+    %(test)s
 test =
     pytest
     respx
+    mypy
+    types-PyYAML
+    pre-commit 
 
 docs =
     sphinx