Merge pull request #386 from bento-platform/docs-and-dev-image

Update docs setup, remove virtualenv use in dev image, add VSCode debug support

.readthedocs.yml

@@ -4,6 +4,11 @@
 # Required
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
@@ -16,7 +21,6 @@ formats:
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.6
   install:
     - requirements: docs/requirements.txt
-    - requirements: requirements.txt
+    - path: .

.vscode/launch.json

@@ -1,8 +1,4 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-
     "version": "0.2.0",
     "configurations": [
         {
@@ -19,11 +15,11 @@
             "django": true
         },
         {
-            "name": "Python: Attach Debugger",
+            "name": "Python: Attach Debugger (Bento)",
             "type": "python",
             "request": "attach",
             "port": 5678,
             "host": "0.0.0.0"
-        },
+        }
     ]
-  }
+}

README.md

@@ -245,6 +245,16 @@ tox
 coverage html
 ```
 
+### Developing and debugging inside a container with VS Code (*Bento*)
+
+The development Docker image includes metadata for the 
+[`devcontainer.json`](https://code.visualstudio.com/docs/devcontainers/attach-container)
+specification. Using VS Code, you can attach to a running instance of a `*-dev` Katsu container
+and launch the `Attach Debugger (Bento)` task to set breakpoints and step through code, as well
+as interacting with and Git-committing inside the container via a remote terminal using the 
+pre-configured `bento_user` user, if the `BENTO_GIT_NAME` and `BENTO_GIT_EMAIL` environment
+variables are set.
+
 ### Terminal Commands
 
 Katsu ships with a variety of command-line helpers to facilitate common actions

bento.Dockerfile

@@ -1,4 +1,4 @@
-FROM ghcr.io/bento-platform/bento_base_image:python-debian-2023.02.27
+FROM ghcr.io/bento-platform/bento_base_image:python-debian-2023.03.22
 
 SHELL ["/bin/bash", "-c"]
 

bento.dev.Dockerfile

@@ -1,15 +1,23 @@
-FROM ghcr.io/bento-platform/bento_base_image:python-debian-2023.02.27
+FROM ghcr.io/bento-platform/bento_base_image:python-debian-2023.03.22
+
+LABEL org.opencontainers.image.description="Local development image for Katsu."
+LABEL devcontainer.metadata='[{ \
+  "remoteUser": "bento_user", \
+  "customizations": { \
+    "vscode": { \
+      "extensions": ["ms-python.python", "eamodio.gitlens"], \
+      "settings": {"workspaceFolder": "/app"} \
+    } \
+  } \
+}]'
 
 SHELL ["/bin/bash", "-c"]
 
 # Install Postgres client for checking if database is ready
 # Install Poetry for dependency management
-#  - For development, install dependencies inside a venv so the developer can interact / change them
 RUN apt-get update -y && \
     apt-get install -y postgresql-client && \
     rm -rf /var/lib/apt/lists/* && \
-    python -m venv /env && \
-    source /env/bin/activate && \
     pip install --no-cache-dir "uvicorn[standard]==0.20.0"
 
 # Backwards-compatible with old BentoV2 container layout
@@ -22,7 +30,7 @@ COPY poetry.toml .
 # Install production + development dependencies
 # Without --no-root, we get errors related to the code not being copied in yet.
 # But we don't want the code here, otherwise Docker cache doesn't work well.
-RUN source /env/bin/activate && poetry install --no-root
+RUN poetry install --no-root
 
 # Create temporary directory for downloading files etc.
 RUN mkdir -p /app/tmp

docs/conf.py

@@ -10,33 +10,32 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import configparser
+
 import datetime
 import os
 import sys
 import django
+import toml
 
 from pathlib import Path
 
 sys.path.insert(0, os.path.abspath('..'))
 os.environ['DJANGO_SETTINGS_MODULE'] = 'chord_metadata_service.metadata.settings'
 django.setup()
 
-config = configparser.ConfigParser()
-config.read(os.path.join(Path(os.path.dirname(os.path.realpath(__file__))).parent,
-                         "chord_metadata_service",
-                         "package.cfg"))
+with open(Path(__file__).parent.parent / "pyproject.toml", "r") as cfh:
+    config = toml.load(cfh)
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'Katsu Metadata service'
-author = config["package"]["authors"]
+author = ", ".join(config["tool"]["poetry"]["authors"])
 # noinspection PyShadowingBuiltins
 copyright = f"{datetime.datetime.now().year} {author}"
 
 # The full version, including alpha/beta/rc tags
-release = config["package"]["version"]
+release = config["tool"]["poetry"]["version"]
 
 version = ".".join(release.split(".")[:2])
 
@@ -53,7 +52,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**/site-packages/*']
 
 
 # -- Options for HTML output -------------------------------------------------

docs/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to Katsu Metadata service's documentation!
-============================================
+==================================================
 
 .. toctree::
    :maxdepth: 2

docs/requirements.txt

@@ -1,12 +1,27 @@
 alabaster==0.7.12
+asgiref==3.6.0
+Babel==2.12.1
+certifi==2022.12.7
+charset-normalizer==3.1.0
+Django==4.1.7
 docutils==0.16
-jinja2<3.1
-setuptools==65.5.1
+idna==3.4
+imagesize==1.4.1
+Jinja2==3.0.3
+MarkupSafe==2.1.2
+packaging==23.0
+Pygments==2.14.0
+requests==2.28.2
+snowballstemmer==2.2.0
 Sphinx==2.4.4
-sphinx-rtd-theme==0.4.3
-sphinxcontrib-applehelp==1.0.2
+sphinx-rtd-theme==1.2.0
+sphinxcontrib-applehelp==1.0.4
 sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.4
+sphinxcontrib-serializinghtml==1.1.5
+sqlparse==0.4.3
+toml==0.10.2
+urllib3==1.26.15

entrypoint.bash

@@ -11,9 +11,6 @@ mkdir -p /app/tmp
 # Fix permissions on /app/tmp and /env
 chown -R bento_user:bento_user /app/tmp
 chmod -R o-rwx /app/tmp  # Remove all access from others
-if [[ -d /env ]]; then
-  chown -R bento_user:bento_user /env
-fi
 
 # Drop into bento_user from root and execute the CMD specified for the image
 exec gosu bento_user "$@"