Documentation: cleanup devcontainer docs and move into tasks and launch config files

.devcontainer/README.md

@@ -1,117 +0,0 @@
-# Paperless NGX Development Environment
-
-## Overview
-
-Welcome to the Paperless NGX development environment! This setup uses VSCode DevContainers to provide a consistent and seamless development experience.
-
-### What are DevContainers?
-
-DevContainers are a feature in VSCode that allows you to develop within a Docker container. This ensures that your development environment is consistent across different machines and setups. By defining a containerized environment, you can eliminate the "works on my machine" problem.
-
-### Advantages of DevContainers
-
-- **Consistency**: Same environment for all developers.
-- **Isolation**: Separate development environment from your local machine.
-- **Reproducibility**: Easily recreate the environment on any machine.
-- **Pre-configured Tools**: Include all necessary tools and dependencies in the container.
-
-## DevContainer Setup
-
-The DevContainer configuration provides up all the necessary services for Paperless NGX, including:
-
-- Redis
-- Gotenberg
-- Tika
-
-Data is stored using Docker volumes to ensure persistence across container restarts.
-
-## Configuration Files
-
-The setup includes debugging configurations (`launch.json`) and tasks (`tasks.json`) to help you manage and debug various parts of the project:
-
-- **Backend Debugging:**
-  - `manage.py runserver`
-  - `manage.py document-consumer`
-  - `celery`
-- **Maintenance Tasks:**
-  - Create superuser
-  - Run migrations
-  - Recreate virtual environment (`.venv` with pipenv)
-  - Compile frontend assets
-
-## Getting Started
-
-### Step 1: Running the DevContainer
-
-To start the DevContainer:
-
-1. Open VSCode.
-2. Open the project folder.
-3. Open the command palette:
-   - **Windows/Linux**: `Ctrl+Shift+P`
-   - **Mac**: `Cmd+Shift+P`
-4. Type and select `Dev Containers: Rebuild and Reopen in Container`.
-
-VSCode will build and start the DevContainer environment.
-
-### Step 2: Initial Setup
-
-Once the DevContainer is up and running, perform the following steps:
-
-1. **Compile Frontend Assets**:
-
-   - Open the command palette:
-     - **Windows/Linux**: `Ctrl+Shift+P`
-     - **Mac**: `Cmd+Shift+P`
-   - Select `Tasks: Run Task`.
-   - Choose `Frontend Compile`.
-
-2. **Run Database Migrations**:
-
-   - Open the command palette:
-     - **Windows/Linux**: `Ctrl+Shift+P`
-     - **Mac**: `Cmd+Shift+P`
-   - Select `Tasks: Run Task`.
-   - Choose `Migrate Database`.
-
-3. **Create Superuser**:
-   - Open the command palette:
-     - **Windows/Linux**: `Ctrl+Shift+P`
-     - **Mac**: `Cmd+Shift+P`
-   - Select `Tasks: Run Task`.
-   - Choose `Create Superuser`.
-
-### Debugging and Running Services
-
-You can start and debug backend services either as debugging sessions via `launch.json` or as tasks.
-
-#### Using `launch.json`:
-
-1. Press `F5` or go to the **Run and Debug** view in VSCode.
-2. Select the desired configuration:
-   - `Runserver`
-   - `Document Consumer`
-   - `Celery`
-
-#### Using Tasks:
-
-1. Open the command palette:
-   - **Windows/Linux**: `Ctrl+Shift+P`
-   - **Mac**: `Cmd+Shift+P`
-2. Select `Tasks: Run Task`.
-3. Choose the desired task:
-   - `Runserver`
-   - `Document Consumer`
-   - `Celery`
-
-### Additional Maintenance Tasks
-
-Additional tasks are available for common maintenance operations:
-
-- **Recreate .venv**: For setting up the virtual environment using pipenv.
-- **Migrate Database**: To apply database migrations.
-- **Create Superuser**: To create an admin user for the application.
-
-## Let's Get Started!
-
-Follow the steps above to get your development environment up and running. Happy coding!

.devcontainer/vscode/launch.json

@@ -3,6 +3,7 @@
     "configurations": [
         {
             "name": "Chrome: Debug Angular Frontend",
+						"description": "Debug the Angular Dev Frontend in Chrome",
             "type": "chrome",
             "request": "launch",
             "url": "http://localhost:4200",
@@ -11,6 +12,7 @@
         },
         {
             "name": "Debug: Backend Server (manage.py runserver)",
+						"description": "Debug the Django Backend Server",
             "type": "python",
             "request": "launch",
             "program": "${workspaceFolder}/src/manage.py",
@@ -26,6 +28,7 @@
         },
         {
             "name": "Debug: Consumer Service (manage.py document_consumer)",
+						"description": "Debug the Consumer Service which processes files from a directory",
             "type": "python",
             "request": "launch",
             "program": "${workspaceFolder}/src/manage.py",
@@ -43,6 +46,7 @@
     "compounds": [
         {
             "name": "Debug: FullStack",
+						"description": "Debug run the Angular dev frontend, Django backend, and consumer service",
             "configurations": [
                 "Chrome: Debug Angular Frontend",
                 "Debug: Backend Server (manage.py runserver)",

.devcontainer/vscode/tasks.json

@@ -3,6 +3,7 @@
 	"tasks": [
 		{
 			"label": "Start: Celery Worker",
+			"description": "Start the Celery Worker which processes background and consume tasks",
 			"type": "shell",
 			"command": "pipenv run celery --app paperless worker -l DEBUG",
 			"isBackground": true,
@@ -26,11 +27,11 @@
 						"endsPattern": "ready"
 					}
 				}
-			],
+			]
-			"detail": ""
 		},
 		{
 			"label": "Start: Frontend Angular",
+			"description": "Start the Frontend Angular Dev Server",
 			"type": "shell",
 			"command": "npm start",
 			"isBackground": true,
@@ -54,11 +55,11 @@
 						"endsPattern": "Compiled successfully"
 					}
 				}
-			],
+			]
-			"detail": "triggered also by launch option Chrome: Debug Angular Frontend"
 		},
 		{
 			"label": "Start: Consumer Service (manage.py document_consumer)",
+			"description": "Start the Consumer Service which processes files from a directory",
 			"type": "shell",
 			"command": "pipenv run python manage.py document_consumer",
 			"group": "build",
@@ -77,6 +78,7 @@
 		},
 		{
 			"label": "Start: Backend Server (manage.py runserver)",
+			"description": "Start the Backend Server which serves the Django API and the compiled Angular frontend",
 			"type": "shell",
 			"command": "pipenv run python manage.py runserver",
 			"group": "build",
@@ -95,6 +97,7 @@
 		},
 		{
 			"label": "Maintenance: manage.py migrate",
+			"description": "Apply database migrations",
 			"type": "shell",
 			"command": "pipenv run python manage.py migrate",
 			"group": "none",
@@ -113,6 +116,7 @@
 		},
 		{
 			"label": "Maintenance: Build Documentation",
+			"description": "Build the documentation with MkDocs",
 			"type": "shell",
 			"command": "pipenv run mkdocs build --config-file mkdocs.yml && pipenv run mkdocs serve",
 			"group": "none",
@@ -131,6 +135,7 @@
 		},
 		{
 			"label": "Maintenance: manage.py createsuperuser",
+			"description": "Create a superuser",
 			"type": "shell",
 			"command": "pipenv run python manage.py createsuperuser",
 			"group": "none",
@@ -147,44 +152,9 @@
 				"cwd": "${workspaceFolder}/src"
 			}
 		},
-		{
-			"label": "Maintenance: Install Angular CLI",
-			"type": "shell",
-			"command": "npm ci && ./node_modules/.bin/ng build --configuration production",
-			"group": "none",
-			"presentation": {
-				"echo": true,
-				"reveal": "always",
-				"focus": true,
-				"panel": "shared",
-				"showReuseMessage": false,
-				"clear": true,
-				"revealProblems": "onProblem"
-			},
-			"options": {
-				"cwd": "${workspaceFolder}/src-ui"
-			}
-		},
-		{
-			"label": "Maintenance: Compile frontend for production",
-			"type": "shell",
-			"command": "npm ci && ./node_modules/.bin/ng build --configuration production",
-			"group": "none",
-			"presentation": {
-				"echo": true,
-				"reveal": "always",
-				"focus": true,
-				"panel": "shared",
-				"showReuseMessage": false,
-				"clear": true,
-				"revealProblems": "onProblem"
-			},
-			"options": {
-				"cwd": "${workspaceFolder}/src-ui"
-			}
-		},
 		{
 			"label": "Maintenance: recreate .venv",
+			"description": "Recreate the python virtual environment and install python dependencies",
 			"type": "shell",
 			"command": "rm -R -v .venv/* || pipenv install --dev",
 			"group": "none",
@@ -203,6 +173,7 @@
 		},
 		{
 			"label": "Maintenance: Install Frontend Dependencies",
+			"description": "Install frontend (npm) dependencies",
 			"type": "npm",
 			"script": "install",
 			"path": "src-ui",
@@ -210,8 +181,28 @@
 			"problemMatcher": [],
 			"detail": "install dependencies from package"
 		},
+		{
+			"description": "Clean install frontend dependencies and build the frontend for production",
+			"label": "Maintenance: Compile frontend for production",
+			"type": "shell",
+			"command": "npm ci && ./node_modules/.bin/ng build --configuration production",
+			"group": "none",
+			"presentation": {
+				"echo": true,
+				"reveal": "always",
+				"focus": true,
+				"panel": "shared",
+				"showReuseMessage": false,
+				"clear": true,
+				"revealProblems": "onProblem"
+			},
+			"options": {
+				"cwd": "${workspaceFolder}/src-ui"
+			}
+		},
 		{
 			"label": "Project Setup: Run all Init Tasks",
+			"description": "Runs all init tasks to setup the project including migrate the database, create a superuser and compile the frontend for production",
 			"dependsOrder": "sequence",
 			"dependsOn": [
 				"Maintenance: manage.py migrate",
@@ -221,6 +212,7 @@
 		},
 		{
 			"label": "Project Start: Run all Services",
+			"description": "Runs all services required to start the project including the Celery Worker, the Consumer Service and the Backend Server",
 			"dependsOn": [
 				"Start: Celery Worker",
 				"Start: Consumer Service (manage.py document_consumer)",

docs/development.md

@@ -457,6 +457,9 @@ Another easy way to get started with development is to use Visual Studio
 Code devcontainers. This approach will create a preconfigured development
 environment with all of the required tools and dependencies.
 [Learn more about devcontainers](https://code.visualstudio.com/docs/devcontainers/containers).
+The .devcontainer/vscode/tasks.json and .devcontainer/vscode/launch.json files
+contain more information about the specific tasks and launch configurations (see the
+non-standard "description" field).
 
 To get started: