docs: unfold development in containers (#979)

lukasvinclav · web-flow · commit 99a4c6de9aeb · 2025-01-16T19:39:05.000+01:00
diff --git a/docs/development/devcontainer.md b/docs/development/devcontainer.md
@@ -0,0 +1,45 @@
+---
+title: VS Code devcontainers
+order: 1
+description: Learn how to set up and use VS Code devcontainers for efficient Unfold theme development, including Tailwind compilation and development server configuration.
+---
+
+# Using VS Code with containers
+
+Unfold already contains prepared support for VS Code development. After cloning the project locally, open the main folder in VS Code (in terminal using `code .`). You will immediately see a message from VS Code stating **Folder contains a Dev Container configuration file. Reopen folder to develop in a container**. This indicates that container support is ready. Click on **Reopen in Container** to proceed. If you don't see this message, you can still manually open the project in a container by running the command **Dev Containers: Reopen in Container**.
+
+## Development server
+
+VS Code will build an image and install Python dependencies. After the installation is complete, VS Code will start a container where you can develop directly. Unfold contains an example development application with basic Unfold configuration available in the `tests/server` directory. To start a development Django server, navigate to the `tests/server` folder and run `python manage.py runserver 0.0.0.0:8000`. Make sure to run this command from the VS Code terminal that is connected to the running container.
+
+**Note:** This is not a production-ready server. Use it only for running tests or developing features & fixes.
+
+## Compiling Tailwind in devcontainer
+
+Before building the styles, you need to install node dependencies since the current Docker image only contains Python dependencies. To enable node in the container, update the `.devcontainer/devcontainer.json` file by adding the following:
+
+```json
+// .devcontainer/devcontainer.json
+
+"features": {
+  "ghcr.io/devcontainers/features/node:1": {
+    "version": "latest"
+  }
+}
+```
+
+This modification is necessary because the `features` are not functioning correctly in Cursor. This approach ensures compatibility with both Cursor and VS Code. Please note that after this change, the container will only work in VS Code and will require more time to start. After making this change, you must rebuild the container by running `Dev Containers: Rebuild Container` in VS Code.
+
+Open the terminal and run `npm install` to install all dependencies and create the `node_modules` folder. You can then use the following npm commands for Tailwind:
+
+```bash
+# Run during development to watch for changes
+npm run tailwind:watch
+
+# Run for a one-time build
+npm run tailwind:build
+```
+
+## Running without VS Code
+
+If you prefer to run the project without VS Code, you can use `docker compose up` from the `.devcontainer` folder. This will automatically start a container and run the migrations and development server.
diff --git a/docs/development/index.md b/docs/development/index.md
@@ -1,67 +1,4 @@
 ---
 title: Development
 order: 12
-description: Development guide and best practices for Unfold.
 ---
-
-# Development
-
-## Pre-commit
-
-Before adding any source code, it is recommended to have pre-commit installed on your local computer to check for all potential issues when committing the code.
-
-```bash
-pip install pre-commit
-pre-commit install
-pre-commit install --hook-type commit-msg
-pre-commit run --all-files # Check if everything is okay
-```
-
-## Poetry configuration
-
-To add a new feature or fix the easiest approach is to use django-unfold in combination with Poetry. The process looks like:
-
-- Install django-unfold via `poetry add django-unfold`
-- After that it is needed to git clone the repository somewhere on local computer.
-- Edit _pyproject.toml_ and update django-unfold line `django-unfold = { path = "../django-unfold", develop = true}`
-- Lock and update via `poetry lock && poetry update`
-
-## Compiling Tailwind
-
-At the moment project contains package.json with all dependencies required to compile new CSS file. Tailwind configuration file is set to check all html, js and py files for Tailwind's classes occurrences.
-
-```bash
-npm install
-npx tailwindcss -i src/unfold/styles.css -o src/unfold/static/unfold/css/styles.css --watch --minify
-
-npm run tailwind:watch # run after each change in code
-npm run tailwind:build # run once
-```
-
-Some components like datepickers, calendars or selectors in admin was not possible to style by overriding html templates so their default styles are overridden in **styles.css**.
-
-**Note:** most of the custom styles located in style.css are created via `@apply some-tailwind-class;` as is not possible to manually add CSS class to element which are for example created via jQuery.
-
-## Design system
-
-| Component                         | Classes                                                |
-| --------------------------------- | ------------------------------------------------------ |
-| Regular text                      | text-base-600 dark:text-base-300                       |
-| Hover regular text                | text-base-700 dark:text-base-200                       |
-| Headings                          | font-semibold text-base-900 dark:text-base-100         |
-| Icon                              | text-base-400 dark:text-base-500                       |
-| Hover icon                        | hover:text-base-500 dark:hover:text-base-400           |
-
-## Using VS Code with containers
-
-Unfold already contains prepared support for VS Code development. After cloning the project locally, open the main folder in VS Code (in terminal `code .`). Immediately, you would see a message from VS Code **Folder contains a Dev Container configuration file. Reopen folder to develop in a container** which will inform you that the support for containers is prepared. Confirm the message by clicking on **Reopen in Container**. If the message is not there, you can still manually open the project in a container by running the command **Dev Containers: Reopen in Container**.
-
-### Development server
-
-Now the VS Code will build an image and install Python dependencies. After successful installation is completed, VS Code will spin a container and from now it is possible to directly develop in the container. Unfold contains an example development application with the basic Unfold configuration available under `tests/server`. Run `python manage.py runserver` within a `tests/server` folder to start a development Django server. Note that you have to run the command from VS Code terminal which is already connected to the running container.
-
-**Note:** this is not a production ready server. Use it just for running tests or developing features & fixes.
-
-### Compiling Tailwind in devcontainer
-
-The container has already a node preinstalled so it is possible to compile a new CSS. Open the terminal and run `npm install` which will install all dependencies and will create `node_modules` folder. Now, you can run npm commands for Tailwind as described in the previous chapter.
diff --git a/docs/development/poetry-dependency.md b/docs/development/poetry-dependency.md
@@ -0,0 +1,50 @@
+---
+title: Poetry dependecy path
+order: 0
+description: Learn how to set up pre-commit hooks, configure Poetry for development, and compile Tailwind CSS styles for Unfold theme development.
+---
+
+# Developing with changed Poetry path
+
+The easiest way how to develop new features or fixes for Unfold is to directly implement them in existing project which you are working on. The prerequisite is to have django-unfold installed and the same time use Poetry for dependency management.
+
+## Poetry configuration
+
+To add a new feature or fix an issue, the easiest approach is to use django-unfold with Poetry. The process looks like this:
+
+- Install django-unfold via `poetry add django-unfold`
+- Clone the repository to your local computer
+- Edit _pyproject.toml_ and update the django-unfold line to: `django-unfold = { path = "../django-unfold", develop = true}`
+- Lock and update via `poetry lock && poetry update`
+
+## Compiling Tailwind
+
+The project contains a package.json with all dependencies required to compile the CSS file. The Tailwind configuration file is set to check all HTML, JS and Python files for Tailwind class occurrences. The prerequisite is to have Node.js installed on your computer.
+
+```bash
+# Install dependencies
+npm install
+
+# Manually run tailwindcss command
+npx tailwindcss -i src/unfold/styles.css -o src/unfold/static/unfold/css/styles.css --watch --minify
+
+# run after each change in code
+npm run tailwind:watch
+# run once
+npm run tailwind:build
+```
+
+Some components like datepickers, calendars or selectors in the admin interface cannot be styled by overriding HTML templates, so their default styles are overridden in **styles.css**.
+
+**Note:** Most of the custom styles in styles.css are created via `@apply some-tailwind-class;` as it is not possible to manually add CSS classes to elements that are created via jQuery.
+
+## Pre-commit
+
+Before adding any source code, it is recommended to have pre-commit installed on your local computer to check for potential issues when committing code.
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit install --hook-type commit-msg
+pre-commit run --all-files # Check if everything is okay
+```
