Merge pull request #215 from DoubleML/dev

Update stable docs version

Author: SvenKlaassen

.devcontainer/Dockerfile.dev

@@ -0,0 +1,73 @@
+FROM ubuntu:24.04
+
+# Set non-interactive mode to avoid prompts
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Update package list and install dependencies
+RUN apt-get update && \
+    apt-get install -y \
+    software-properties-common \
+    graphviz \
+    wget \
+    dirmngr \
+    gnupg \
+    apt-transport-https \
+    ca-certificates \
+    git \
+    cmake
+
+# Install locale packages
+RUN apt-get update && \
+    apt-get install -y locales && \
+    locale-gen en_US.UTF-8 && \
+    update-locale LANG=en_US.UTF-8
+
+# Set environment variables for locale
+ENV LANG=en_US.UTF-8
+ENV LANGUAGE=en_US:en
+ENV LC_ALL=en_US.UTF-8
+
+# Install Python 3.12
+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
+
+# 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
+
+# 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"
+
+# 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]
+
+# Create a directory for R user libraries and set the default R user library path
+RUN mkdir -p /usr/local/lib/R/site-library
+ENV R_LIBS_USER=/usr/local/lib/R/site-library
+
+# Install R packages and Jupyter kernel
+RUN Rscript -e "install.packages('remotes')" && \
+    Rscript -e "remotes::install_github('DoubleML/doubleml-for-r', dependencies = TRUE)" && \
+    Rscript -e "install.packages(c('ggplot2', 'IRkernel', 'xgboost', 'hdm', 'reshape2', 'gridExtra', 'igraph', 'mlr3filters', 'mlr3measures', 'did', dependencies=TRUE))" && \
+    Rscript -e "IRkernel::installspec()"
+
+# Set the working directory
+WORKDIR /workspace
+

.devcontainer/devcontainer.json

@@ -0,0 +1,46 @@
+{
+	"name": "DoubleML Documentation Development",
+	"dockerFile": "Dockerfile.dev", // Path to your Dockerfile
+	"context": "..", // Context for the build (root of your project)
+	"workspaceFolder": "/workspace", // Folder inside the container for your project
+	// Customizations for VS Code
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python", // Python extension for VS Code
+				"ms-azuretools.vscode-docker", // Docker integration for VS Code
+				"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.github-vscode-theme", // GitHub theme
+				"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
+				"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.testing.pytestArgs": [],
+				"python.testing.unittestEnabled": false,
+				"files.exclude": {
+					"**/__pycache__": true, // Hide __pycache__ directories
+					"**/*.pyc": true, // Hide .pyc files
+					"**/.DS_Store": true // Hide .DS_Store files (macOS)
+				}
+			}
+		}
+	},
+	"mounts": [
+		"source=${localWorkspaceFolder},target=/workspace,type=bind" // Mount your local workspace into the container
+	],
+	"remoteUser": "root" // Set the user inside the container
+}

.devcontainer/guide.md

@@ -0,0 +1,64 @@
+# 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/)
+
+## 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).
+   - Open Docker Desktop.
+   - Go to **Settings > General** and make sure **Use the WSL 2 based engine** is checked.
+   - Under **Settings > Resources > WSL Integration**, ensure that your desired Linux distribution(s) are selected for integration with Docker.
+
+### Install Extensions
+
+   - Open Visual Studio Code.
+   - Press `Ctrl+Shift+X` to open the Extensions view.
+   - 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)
+
+   VS Code Documentations:
+   - [Developing in WSL](https://code.visualstudio.com/docs/remote/wsl)
+   - [Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers)
+
+
+## Build & Open the Development Container
+
+   - Open the project `doubleml-docs` in VS code:
+
+   ```bash
+   code .
+   ```
+
+   - Open the Command Palette (`Ctrl+Shift+P`).
+   - Type `Remote-Containers: Reopen Folder in Container`.
+   - VS Code will build the new container(this may take some time) and open the project in it.
+
+
+## Build the documentation
+
+You can build the documentation via
+
+   ```bash
+   cd doc
+   make html
+   ```
+
+   Open the directory in WSL with
+   ```bash
+   explorer.exe .
+   ```

.github/workflows/deploy_docu_dev.yml

@@ -76,7 +76,7 @@ jobs:
 
     - name: Build docu with sphinx
       run: |
-        make -C doc html # build docu
+        make -C doc html
 
     - name: Deploy to dev
       uses: JamesIves/github-pages-deploy-action@v4

.github/workflows/deploy_docu_stable.yml

@@ -65,7 +65,7 @@ jobs:
 
     - name: Build docu with sphinx
       run: |
-        make -C doc html # build docu
+        make -C doc html
 
     - name: Deploy to stable
       uses: JamesIves/github-pages-deploy-action@v4

.github/workflows/test_build_docu_dev.yml

@@ -20,6 +20,10 @@ on:
         description: 'Branch in https://github.com/DoubleML/doubleml-for-r'
         required: true
         default: 'main'
+      nbsphinx-execute:
+        description: 'Execute notebooks with nbsphinx'
+        required: false
+        default: 'auto'
   schedule:
     - cron: "0 9 * * 1,3,5"
 
@@ -113,7 +117,7 @@ jobs:
 
     - name: Build docu with sphinx
       run: |
-        make -C doc html # build docu
+        make -C doc html NBSPHINX_EXECUTE=${{ github.event.inputs.nbsphinx-execute || 'auto' }}
 
     - name: Check for broken links / URLs
       run: |

.github/workflows/test_build_docu_released.yml

@@ -11,6 +11,11 @@ on:
       - main
       - dev
   workflow_dispatch:
+    inputs:
+      nbsphinx-execute:
+        description: 'Execute notebooks with nbsphinx'
+        required: false
+        default: 'auto'
   schedule:
     - cron: "0 9 * * 1,3,5"
 
@@ -74,9 +79,10 @@ jobs:
 
     - name: Build docu with sphinx
       run: |
-        make -C doc html # build docu
+        make -C doc html NBSPHINX_EXECUTE=${{ github.event.inputs.nbsphinx-execute || 'auto' }}
 
     - name: Check for broken links / URLs
+
       run: |
         make -C doc linkcheck
 

.idea/.gitignore

@@ -1 +1,4 @@
 _build
+
+# Ignore generated API documentation
+api/generated/

.idea/doubleml-docs.iml

@@ -7,6 +7,11 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
+NBSPHINX_EXECUTE = auto
+
+# Add NBSPHINX_EXECUTE to SPHINXOPTS
+SPHINXOPTS   += -D nbsphinx_execute=$(NBSPHINX_EXECUTE)
+
 
 # Put it first so that "make" without argument is like "make help".
 help:

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,13 @@
+[
+    {
+        "name": "dev",
+        "version": "dev",
+        "url": "https://docs.doubleml.org/dev/"
+    },
+    {
+        "name": "stable",
+        "version": "stable",
+        "url": "https://docs.doubleml.org/stable/",
+        "preferred": true
+    }
+]