Add docs and workflows for distributing packages (#35)

* Add docs/demo.ipynb to .gitignore

* A docs and workflow for publishing to pypi

* Add workflow of publishing docker image

Author: finsberg

.github/workflows/docker-image.yml

@@ -0,0 +1,49 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Create and publish a Docker image
+
+on:
+  push:
+    branches:
+      - "!*"
+    tags:
+      - "v*"
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/pypi.yml

@@ -0,0 +1,43 @@
+name: PyPI
+
+on:
+  push:
+    # The CI is executed on every push on every branch
+    branches:
+      - main
+  pull_request:
+    # The CI is executed on every pull request to the main branch
+    branches:
+      - main
+
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: python3 -m pip install ".[pypi]"
+
+      - name: Build a binary wheel and a source tarball
+        run: >-
+          python3 -m
+          build
+          --sdist
+          --wheel
+          --outdir dist/
+          .
+
+      - name: Publish distribution 📦 to PyPI
+        if: startsWith(github.ref, 'refs/tags')  # Only push to pypi when there is a new tag
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -1,3 +1,5 @@
+docs/demo.ipynb
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

docs/_toc.yml

@@ -32,8 +32,14 @@ parts:
     # The following file should be autogenerated by the Makefile
     - file: "demo.ipynb"
 
+  - caption: Distribution
+    chapters:
+    - file: "part4/pypi"
+    - file: "part4/conda"
+    - file: "part4/docker"
+
   - caption: Other Features
     chapters:
-    - file: "part4/badges"
+    - file: "part5/badges"
 
 

docs/part4/conda.md

@@ -0,0 +1,5 @@
+# Publishing conda package
+
+TBW
+
+## Uploading your package to conda-forge

docs/part4/docker.md

@@ -0,0 +1,3 @@
+# Publishing docker image for your package
+
+Publishing a docker image is perhaps one of the best ways to make sure that people are able to run your package in exactly the same environment as you. GitHub has the possibility to [publish docker images](https://docs.github.com/en/actions/publishing-packages/publishing-docker-images) as a part of GitHub packages

docs/part4/pypi.md

@@ -0,0 +1,10 @@
+# Publishing package to pypi
+
+Whenever you have a package that you want to share with others, you need a way to distribute it with others. Sharing your package through a repository at GitHub is one way, but most programming langues have their own way of distributing packages. For example `node` uses [npm](https://www.npmjs.com), `rust` uses [`crates.io`](https://crates.io) and `julia` uses [`Pkg`](https://docs.julialang.org/en/v1/stdlib/Pkg/)
+
+Python uses the [Python Packaging Index (PyPI)](https://pypi.org) where the process is to first build a wheel of your package and then upload this wheel to the index. You can do everything with a package called [`build`](https://github.com/pypa/build), and of course you can [automate the process using GitHub actions](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
+
+
+## Building multiple wheels using `cibuildwheel`
+
+If your package contains extensions written in another language than python then you might need to build wheels for different platforms and architectures. In this case you can use a tool such as [`cibuildwheel`](https://cibuildwheel.readthedocs.io/en/stable/).

docs/part4/badges.md renamed to docs/part5/badges.md

@@ -34,6 +34,9 @@ binder = [ # Required to interface with Binder when having a Dockerfile in root
     "jupyterlab",
     "notebook"
 ]
+pypi = [
+    "build" # Used for building wheels and uploading to pypi
+]
 
 [tool.mypy]
 ignore_missing_imports = true # Does not show errors when importing untyped libraries