feat: add VS Code support files to template

Author: liborjelinek

.gitignore

@@ -23,4 +23,5 @@ node_modules
 # editors
 .idea/
 .vscode/*
-!.vscode/*.sample
+!.vscode/*.sample
+!.vscode/extensions.json

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2025-03-11
+
+- feat: add VS Code support files to template
+
 ## [0.1.0] - 2025-03-09
 
 Initial release.

README.md

@@ -46,10 +46,10 @@ The recommended way to install the Copier is [uv](https://docs.astral.sh/uv/). T
 With uv installed, open the terminal and
 
 ```
-uvx copier copy https://github.com/documatt/sphinx-theme-template my-new-theme
+uvx copier copy gh:documatt/sphinx-theme-template my-new-theme
 ```
 
-Answer the series of questions, and you are ready to go. You have the skeleton of a completely functional Sphinx theme in `my-new-theme` folder in just a few moments.
+Answer the series of questions, and you are ready to go. You have the skeleton of a completely functional Sphinx theme in `my-new-theme` folder in just a few moments. Use `.` for the current folder.
 
 ## Key Features
 

docs/source/_static/vscode-venv-detected.png

@@ -6,25 +6,29 @@
 [Nox]: https://nox.thea.codes/
 [uv]: https://docs.astral.sh/uv/
 
-You will need Python and two Python tools:
+For Sphinx and automation, you will need Python and two Python tools:
 
 - [Copier]: scaffolding tool that will generate from this template a Sphinx theme on your disk
 - [Nox]: automation tool for easier building docs from project sources
 
 The recommended way to install and run is using the [uv] tool. The uv can even install Python for you if you don't have it already.
 
-1. [**Install uv**](https://docs.astral.sh/uv/getting-started/installation/) for your environment.
+You will also need Node.js and npm tool installed. Sphinx themes are basically websites, and this template comes preconfigured for development with [Tailwind CSS](https://tailwindcss.com), a Node.js based tool. Additionally, a few developer tools preconfigured are Node.js based, such as those for formatting and linting.
+
+1. [**Install uv**](https://docs.astral.sh/uv/getting-started/installation/).
 
    ```{seealso}
    See [Copier docs][Copier] and [Nox docs][Nox] for other installation options if uv is not suitable for you.
    ```
 
+2. [**Install Node.js and npm**](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). We recommend you LTS version.
+
 ## Tutorial
 
 1. **Answer questions.** Open the terminal, choose a destination folder (use `.` for current), and follow the wizard. E.g.,:
 
    ```
-   uvx copier copy https://github.com/documatt/sphinx-theme-template sphinx-my-theme
+   uvx copier copy gh:documatt/sphinx-theme-template sphinx-my-theme
    ```
 
    This command will install and call Copier.
@@ -127,3 +131,19 @@ The recommended way to install and run is using the [uv] tool. The uv can even i
 1. **Enjoy.**
 
 % TODO: See all the other cool [features](features.md) provided by the template.
+
+## VS Code setup
+
+The template comes with improvements to the developer experience when local working in VS Code.
+
+1. VS Code prompts you to install the recommended extensions from `.vscode/extensions.json` when opened for the first time.
+1. Save `.vscode/settings.json.sample` as `settings.json`.
+
+## Local development
+
+1. At project root run `npm i` to install Node.js tools for formatting and liting.
+1. At project root run `uv sync`. This will create virtual environment folder `.venv/`.
+
+   In VS Code, virtual environment folder is automatically detected. VS Code asks you to use it. Then it appears in statusbar.
+   ![](_static/vscode-venv-detected.png)
+   ![](_static/vscode-venv-statusbar.png)

docs/source/_static/vscode-venv-statusbar.png

@@ -23,5 +23,6 @@ node_modules
 
 # editors
 .idea/
-!.vscode/*.sample
-.vscode/*
+.vscode/*
+!.vscode/extensions.json
+!.vscode/*.sample

docs/source/quickstart.md

@@ -0,0 +1,26 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+  // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+  // List of extensions which should be recommended for users of this workspace.
+  "recommendations": [
+    // Prettier formatter
+    "esbenp.prettier-vscode",
+
+    // Python ruff formatter and linter
+    "charliermarsh.ruff",
+
+    // Syntax highlighting for Jinja HTML/CSS/JS and other templates
+    "samuelcolvin.jinjahtml",
+
+    // Tailwind CSS IntelliSense
+    "bradlc.vscode-tailwindcss",
+
+    // MyST markdown syntax highlighting
+    "executablebookproject.myst-highlight",
+
+    // Simple RST syntax highlighting
+    "trond-snekvik.simple-rst"
+  ],
+  // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+  "unwantedRecommendations": []
+}

template/.gitignore

@@ -0,0 +1,28 @@
+{
+  // Format on save
+  "editor.formatOnSave": true,
+
+  // Format and lint Python with Ruff
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.codeActionsOnSave": {
+      // Fix all issues on save
+      "source.fixAll": "explicit",
+      // Organize imports on save
+      "source.organizeImports": "explicit"
+    }
+  },
+
+  // Format everything else with Prettier
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+
+  // Pytest support
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": ["-vv", "--color=yes"],
+
+  "files.associations": {
+    "**/src/**/*.html": "jinja-html",
+    "**/src/**/styles/*.css": "tailwindcss"
+  }
+}

template/.vscode/extensions.json

@@ -23,5 +23,6 @@ node_modules
 
 # editors
 .idea/
-!.vscode/*.sample
-.vscode/*
+.vscode/*
+!.vscode/extensions.json
+!.vscode/*.sample