Merge pull request #227 from DoubleML/dev

Update `main` according to latest changes on `dev`

Author: SvenKlaassen

.devcontainer/Dockerfile.dev

@@ -14,13 +14,12 @@ RUN apt-get update && \
     apt-transport-https \
     ca-certificates \
     git \
-    cmake
-
-# Install locale packages
-RUN apt-get update && \
-    apt-get install -y locales && \
+    cmake \
+    locales && \
     locale-gen en_US.UTF-8 && \
-    update-locale LANG=en_US.UTF-8
+    update-locale LANG=en_US.UTF-8 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
 
 # Set environment variables for locale
 ENV LANG=en_US.UTF-8
@@ -31,37 +30,43 @@ ENV LC_ALL=en_US.UTF-8
 RUN add-apt-repository ppa:deadsnakes/ppa && \
     apt-get update && \
     apt-get install -y python3.12 python3.12-venv python3.12-dev python3-pip python3-full && \
-    apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# Set Python 3.12 as the default for both python and python3
-RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1 && \
-    update-alternatives --install /usr/bin/python python /usr/bin/python3.12 1
+    update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1 && \
+    update-alternatives --install /usr/bin/python python /usr/bin/python3.12 1 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
 
 # Add R repository and install R
 RUN wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | tee /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc && \
     add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu noble-cran40/' && \
     apt-get update && \
-    apt-get install -y r-base r-base-dev zlib1g-dev libicu-dev pandoc make libcurl4-openssl-dev libssl-dev
+    apt-get install -y r-base r-base-dev zlib1g-dev libicu-dev pandoc make libcurl4-openssl-dev libssl-dev && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
 
-# Install Python packages
-COPY requirements.txt /tmp/requirements.txt
-RUN python -m venv /opt/venv && \
-    /opt/venv/bin/python -m pip install --upgrade pip && \
-    /opt/venv/bin/pip install -r /tmp/requirements.txt
-
-# Set the virtual environment as the default Python environment
-ENV PATH="/opt/venv/bin:$PATH"
+# Reuse existing 'ubuntu' user (UID 1000)
+ARG USERNAME=ubuntu
 
-# Check out the repo containing the Python package DoubleML (dev)
-RUN git clone https://github.com/DoubleML/doubleml-for-py.git /doubleml-for-py
-WORKDIR /doubleml-for-py
-RUN /opt/venv/bin/pip uninstall -y DoubleML && \
-    /opt/venv/bin/pip install -e .[rdd]
+RUN mkdir -p /workspace && \
+    chown -R $USERNAME:$USERNAME /workspace
 
-# Create a directory for R user libraries and set the default R user library path
-RUN mkdir -p /usr/local/lib/R/site-library
+# Create a directory for R user libraries
+RUN mkdir -p /usr/local/lib/R/site-library && \
+    chown -R $USERNAME:$USERNAME /usr/local/lib/R/site-library
 ENV R_LIBS_USER=/usr/local/lib/R/site-library
 
+# Switch to non-root user for remaining operations
+USER $USERNAME
+
+# Install Python packages in the virtual environment
+COPY --chown=$USERNAME:$USERNAME requirements.txt /tmp/requirements.txt
+RUN python -m venv /home/$USERNAME/.venv && \
+    /home/$USERNAME/.venv/bin/python -m pip install --upgrade pip && \
+    /home/$USERNAME/.venv/bin/pip install --no-cache-dir -r /tmp/requirements.txt && \
+    /home/$USERNAME/.venv/bin/pip install --no-cache-dir git+https://github.com/DoubleML/doubleml-for-py.git@main#egg=DoubleML[rdd]
+
+# Set the virtual environment as the default Python environment
+ENV PATH="/home/$USERNAME/.venv/bin:$PATH"
+
 # Install R packages and Jupyter kernel
 RUN Rscript -e "install.packages('remotes')" && \
     Rscript -e "remotes::install_github('DoubleML/doubleml-for-r', dependencies = TRUE)" && \
@@ -70,4 +75,3 @@ RUN Rscript -e "install.packages('remotes')" && \
 
 # Set the working directory
 WORKDIR /workspace
-

.devcontainer/build_image_guide.md

@@ -0,0 +1,134 @@
+# Building and Publishing the Docker Image
+
+This guide shows how to build the DoubleML documentation development container locally and publish it to Docker Hub.
+
+## Prerequisites
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running
+- Access to the `svenklaassen` [Docker Hub](https://www.docker.com/products/docker-hub/) account
+- [doubleml-docs](https://github.com/DoubleML/doubleml-docs) repository cloned to your local machine
+
+## Step 1: Login to Docker Hub
+
+Open a terminal and login to Docker Hub:
+
+```bash
+docker login
+```
+
+Enter the Docker Hub username (`svenklaassen`) and password (or token) when prompted.
+
+## Step 2: Build the Docker Image
+
+Navigate to your project root directory and build the image (using the `latest`-tag):
+
+```bash
+docker build -t svenklaassen/doubleml-docs:latest -f .devcontainer/Dockerfile.dev .
+```
+
+To force a complete rebuild without using cache:
+
+```bash
+docker build --no-cache -t svenklaassen/doubleml-docs:latest -f .devcontainer/Dockerfile.dev .
+```
+
+## Step 3 (Optional): Verify the image
+
+### Open the repository in VS Code
+
+1. Ensure your `.devcontainer/devcontainer.json` is configured to use your local image:
+
+    ```json
+    "image": "svenklaassen/doubleml-docs:latest"
+    ```
+    Note: The `.devcontainer/devcontainer.json` file is configured to use the pre-built image. If you want to build the container from scratch, uncomment the `dockerFile` and `context` lines and comment out the `image` line.
+
+2. Open the `doubleml-docs` repository in VS Code:
+
+   ```bash
+   code /path/to/doubleml-docs
+   ```
+
+3. Open the Command Palette (`Ctrl+Shift+P`) and select `Dev Containers: Reopen in Container`.
+   VS Code will use your locally built image.
+
+### Build the documentation
+
+Once inside the container, verify that you can successfully build the documentation:
+
+1. Open a terminal in VS Code (`Terminal > New Terminal`)
+
+2. Build the documentation:
+
+   ```bash
+   cd doc
+   make html
+   ```
+
+3. Check the output for any errors or warnings
+
+4. View the built documentation by opening the output files:
+
+   ```bash
+   # On Windows
+   explorer.exe _build/html
+   
+   # On Linux
+   xdg-open _build/html
+   
+   # On macOS
+   open _build/html
+   ```
+
+If the documentation builds successfully and looks correct, your Docker image is working properly and ready to be pushed to Docker Hub.
+
+## Step 4: Push to Docker Hub
+
+Push your built image to Docker Hub:
+
+```bash
+docker push svenklaassen/doubleml-docs:latest
+```
+
+## Step 5: Using the Published Image
+
+After publishing, there are two ways to use the image:
+
+### Option 1: Manual Container Management
+Pull and run the container manually:
+
+```bash
+docker pull svenklaassen/doubleml-docs:latest
+# Then run commands to create a container from this image
+```
+
+### Option 2: VS Code Integration (Recommended)
+Simply reference the image in your `devcontainer.json` file:
+
+```json
+"image": "svenklaassen/doubleml-docs:latest"
+```
+
+VS Code will automatically pull the image when opening the project in a container - no separate `docker pull` command needed.
+
+## Troubleshooting
+
+### Clear Docker Cache
+
+If you're experiencing issues with cached layers:
+
+```bash
+# Remove build cache
+docker builder prune
+
+# For a more thorough cleanup
+docker system prune -a
+```
+
+### Check Image Size
+
+To verify the image size before pushing:
+
+```bash
+docker images svenklaassen/doubleml-docs
+```

.devcontainer/devcontainer.json

@@ -1,7 +1,8 @@
 {
 	"name": "DoubleML Documentation Development",
-	"dockerFile": "Dockerfile.dev", // Path to your Dockerfile
-	"context": "..", // Context for the build (root of your project)
+	"image": "svenklaassen/doubleml-docs:latest",
+	// "dockerFile": "Dockerfile.dev",
+	// "context": "..",
 	"workspaceFolder": "/workspace", // Folder inside the container for your project
 	// Customizations for VS Code
 	"customizations": {
@@ -12,23 +13,27 @@
 				"njpwerner.autodocstring", // Optional: Auto-generate docstrings
 				"ms-python.black-formatter", // Optional: Black formatter
 				"streetsidesoftware.code-spell-checker", // Optional: Spell checker
-				"github.copilot" // Add GitHub Copilot extension
+				"github.copilot", // Add GitHub Copilot extension
 				"GitHub.github-vscode-theme", // GitHub theme
-				"github.vscode-github-actions" // GitHub Actions extension
+				"github.vscode-github-actions", // GitHub Actions extension
 				"ms-toolsai.jupyter", // Jupyter extension
 				"charliermarsh.ruff" // Ruff extension
 			],
 			"settings": {
-				"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python", // Poetry virtual environment path
+				"python.defaultInterpreterPath": "/home/ubuntu/.venv/bin/python",
 				"editor.formatOnSave": true, // Auto-format code when saving
 				"editor.codeActionsOnSave": {
 					"source.organizeImports": true // Auto-organize imports on save
 				},
 				"python.linting.enabled": true, // Enable linting
 				"python.linting.flake8Enabled": false, // Disable Flake8 for linting
 				"python.linting.ruffEnabled": true, // Enable Ruff for linting
-				"python.formatting.provider": "black", // Use Black for formatting
-				"python.testing.pytestEnabled": false, // Enable Pytest for testing
+				"python.formatting.provider": "none",
+				"[python]": {
+					"editor.defaultFormatter": "ms-python.black-formatter",
+					"editor.formatOnSave": true
+				},
+				"python.testing.pytestEnabled": true, // Enable Pytest for testing
 				"python.testing.pytestArgs": [],
 				"python.testing.unittestEnabled": false,
 				"files.exclude": {
@@ -40,7 +45,8 @@
 		}
 	},
 	"mounts": [
-		"source=${localWorkspaceFolder},target=/workspace,type=bind" // Mount your local workspace into the container
+		"source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached" // Mount your local workspace into the container
 	],
-	"remoteUser": "root" // Set the user inside the container
+	"remoteUser": "ubuntu",
+	"postCreateCommand": "id && ls -la /workspace && echo 'Container is ready!'"
 }

.devcontainer/docker_guide.md

@@ -0,0 +1,83 @@
+# Build Documentation with Development Container
+
+This guide shows how to use WSL2 (Windows Subsystem for Linux), Docker Desktop, Visual Studio Code (VS Code), and how to work with Development Containers in VS Code on a Windows machine.
+
+Requirements:
+ - [VS Code](https://code.visualstudio.com/)
+ - [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)
+ - [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)
+
+## Step 1: Verify installations & Setup
+
+You can verify the installations in a terminal:
+   
+   ```bash
+   code --version
+   wsl --version
+   docker --version
+   ```
+
+### Configure Docker to Use WSL2
+
+   See [Docker Desktop Documentation](https://docs.docker.com/desktop/features/wsl/#turn-on-docker-desktop-wsl-2).
+   1. Open Docker Desktop.
+   2. Go to **Settings > General** and make sure **Use the WSL 2 based engine** is checked.
+   3. Under **Settings > Resources > WSL Integration**, ensure that your desired Linux distribution(s) are selected for integration with Docker.
+
+### Install Extensions
+
+   1. Open Visual Studio Code.
+   2. Press `Ctrl+Shift+X` to open the Extensions view.
+   3. Search and install (includes WSL and Dev Containers Extensions):
+      - [Remote Development Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)
+
+   Helpful VS Code Documentations:
+   - [Developing in WSL](https://code.visualstudio.com/docs/remote/wsl)
+   - [Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers)
+
+
+## Step 2: Open the Development Container (Using Pre-built Image)
+
+For faster setup, we'll use a pre-built Docker image:
+
+1. Open the `doubleml-docs` repository in VS Code:
+
+   ```bash
+   code /path/to/doubleml-docs
+   ```
+
+2. Open the Command Palette (`Ctrl+Shift+P`).
+3. Type `Dev Containers: Reopen in Container`.
+
+VS Code will pull the `svenklaassen/doubleml-docs:latest` image (if needed) based on `devcontainer.json` and open the project in the container.<br>
+This approach is much faster than building the container from scratch. VS Code automatically downloads the image from Docker Hub if it's not already on your system.
+
+
+## Step 3: Build the documentation
+
+1. Open a terminal in VS Code (`Terminal > New Terminal`)
+
+2. Build the documentation:
+
+   ```bash
+   cd doc
+   make html
+   ```
+
+   To build without notebook examples:
+   ```bash
+   make html NBSPHINX_EXECUTE=never
+   ```
+
+3. View the built documentation by opening the output files:
+
+   ```bash
+   # On Windows
+   explorer.exe _build/html
+   
+   # On Linux
+   xdg-open _build/html
+   
+   # On macOS
+   open _build/html
+   ```