add basic documentation

Author: joshuadavidthomas

.gitignore

@@ -189,3 +189,6 @@ Cargo.lock
 *.pdb
 
 # End of https://www.toptal.com/developers/gitignore/api/rust,python
+
+# mkdocs
+site/

.just/docs.just

@@ -0,0 +1,32 @@
+set unstable := true
+
+justfile := justfile_directory() + "/.just/docs.just"
+mkdoc_config := justfile_directory() + "/.mkdocs.yml"
+
+[private]
+default:
+    @just --list --justfile {{ justfile }}
+
+[private]
+fmt:
+    @just --fmt --justfile {{ justfile }}
+
+# Build documentation
+[no-cd]
+build LOCATION="site": process
+    uv run --group docs --frozen mkdocs build --config-file {{ mkdoc_config }} --site-dir {{ LOCATION }}
+
+# Serve documentation locally
+[no-cd]
+serve PORT="8000": process
+    #!/usr/bin/env sh
+    HOST="localhost"
+    if [ -f "/.dockerenv" ]; then
+        HOST="0.0.0.0"
+    fi
+    uv run --group docs --frozen mkdocs serve --config-file {{ mkdoc_config }} --dev-addr localhost:{{ PORT }}
+
+[no-cd]
+[private]
+process:
+    uv run docs/processor.py

.mkdocs.yml

@@ -0,0 +1,55 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+extra_css:
+  - stylesheets/extra.css
+markdown_extensions:
+  - attr_list
+  - admonition
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink:
+      hide_protocol: true
+      repo_url_shortener: true
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+plugins:
+  - search
+repo_url: https://github.com/joshuadavidthomas/django-language-server
+site_author: joshuadavidthomas
+site_name: Django Language Server
+site_url: http://joshuadavidthomas.github.io/django-language-server
+theme:
+  features:
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.sections
+    - navigation.tracking
+    - search.highlight
+    - search.suggest
+  font:
+    code: Fira Code
+    text: Inter
+  icon:
+    repo: fontawesome/brands/github
+  name: material
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+  commands:
+    - asdf plugin add just && asdf install just latest && asdf global just latest
+    - asdf plugin add uv && asdf install uv latest && asdf global uv latest
+    - just docs build $READTHEDOCS_OUTPUT/html
+
+mkdocs:
+  configuration: .mkdocs.yml

Justfile

@@ -1,6 +1,7 @@
 set dotenv-load := true
 set unstable := true
 
+mod docs ".just/docs.just"
 mod proto ".just/proto.just"
 
 # List all available commands

README.md

@@ -13,20 +13,16 @@ A language server for the Django web framework.
 
 However, the foundation has been laid:
 
-✅ Working server architecture
-
-- ✅ Server implementing the Language Server Protocol written in Rust
-- ✅ Python agent running as a persistent process within the Django project's virtualenv
-- ✅ Server-agent communication via Protocol Buffers
-
-✅ Custom template parser to support LSP features
-
-- ✅ Basic HTML parsing, including style and script tags
-- ✅ Django variables and filters
-- ❌ Django block template tags
-  - Early work on extensible template tag parsing specification (TagSpecs)
-
-❌ Actual LSP features (coming soon!... hopefully)
+- [x] Working server architecture
+    - [x] Server implementing the Language Server Protocol written in Rust
+    - [x] Python agent running as a persistent process within the Django project's virtualenv
+    - [x] Server-agent communication via Protocol Buffers
+- [x] Custom template parser to support LSP features
+    - [x] Basic HTML parsing, including style and script tags
+    - [x] Django variables and filters
+    - [ ] Django block template tags
+        - Early work has been done on an extensible template tag parsing specification (TagSpecs)
+- [ ] Actual LSP features (coming soon!... hopefully)
 
 ## Requirements
 
@@ -99,64 +95,11 @@ pip install djls-agent
 
 ## Editor Setup
 
-The Django Language Server should work with any editor that supports the Language Server Protocol (LSP). Got it working in your editor? [Help us add setup instructions!](#testing-and-documenting-editor-setup)
-
-- [Neovim](#neovim)
-
-### Neovim
-
-Using [lazy.nvim](https://github.com/folke/lazy.nvim) and [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig):
-
-```lua
-  {
-    "neovim/nvim-lspconfig",
-    opts = {
-      servers = {
-        djls = {},
-      },
-      setup = {
-        djls = function(_, opts)
-          local configs = require("lspconfig.configs")
-          local util = require("lspconfig.util")
-
-          if not configs.djls then
-            configs.djls = {
-              default_config = {
-                cmd = { "djls", "serve" },
-                filetypes = { "htmldjango" },
-                root_dir = function(fname)
-                  local root = util.root_pattern("manage.py", "pyproject.toml")(fname)
-                  vim.notify("LSP root dir: " .. (root or "nil"))
-                  return root or vim.fn.getcwd()
-                end,
-                handlers = {
-                  ["window/logMessage"] = function(_, params, _)
-                    local message_type = {
-                      [1] = vim.log.levels.ERROR,
-                      [2] = vim.log.levels.WARN,
-                      [3] = vim.log.levels.INFO,
-                      [4] = vim.log.levels.DEBUG,
-                    }
-                    vim.notify(params.message, message_type[params.type], {
-                      title = "djls",
-                    })
-                  end,
-                },
-                on_attach = function(client, bufnr)
-                  vim.notify("djls attached to buffer: " .. bufnr)
-                end,
-              },
-            }
-          end
-          require("lspconfig").djls.setup({})
-        end,
-      },
-    },
-  },
-```
+The Django Language Server works with any editor that supports the Language Server Protocol (LSP). We currently have setup instructions for:
 
-> [!NOTE]
-> This configuration is copied straight from my Neovim setup and includes a logging setup that sends LSP messages to Neovim's notification system. You can remove all the references to `vim.notify` if you don't care about this functionality.
+- [Neovim](/docs/editor-setup/neovim.md)
+
+Got it working in your editor? [Help us add setup instructions!](#testing-and-documenting-editor-setup)
 
 ## Versioning
 
@@ -190,7 +133,10 @@ The project needs help in several areas:
 
 The server has only been tested with Neovim. Documentation for setting up the language server in other editors is sorely needed, particularly VS Code. However, any editor that has [LSP client](https://langserver.org/#:~:text=for%20more%20information.-,LSP%20clients,opensesame%2Dextension%2Dlanguage_server,-Community%20Discussion%20Forums) support would be welcome.
 
-If you get it working in your editor, please open a PR with the setup instructions.
+If you get it working in your editor:
+
+1. Create a new Markdown file in the `docs/editors/` directory (e.g., `docs/editors/vscode.md`)
+2. Include step-by-step setup instructions, any required configuration snippets, and tips for troubleshooting
 
 ### Feature Requests
 

docs/editor-setup/neovim.md

@@ -0,0 +1,55 @@
+# Neovim
+
+Using <https://github.com/folke/lazy.nvim> and <https://github.com/neovim/nvim-lspconfig>:
+
+```lua
+{
+  "neovim/nvim-lspconfig",
+  opts = {
+    servers = {
+      djls = {},
+    },
+    setup = {
+      djls = function(_, opts)
+        local configs = require("lspconfig.configs")
+        local util = require("lspconfig.util")
+
+        if not configs.djls then
+          configs.djls = {
+            default_config = {
+              cmd = { "djls", "serve" },
+              filetypes = { "htmldjango" },
+              root_dir = function(fname)
+                local root = util.root_pattern("manage.py", "pyproject.toml")(fname)
+                vim.notify("LSP root dir: " .. (root or "nil"))
+                return root or vim.fn.getcwd()
+              end,
+              handlers = {
+                ["window/logMessage"] = function(_, params, _)
+                  local message_type = {
+                    [1] = vim.log.levels.ERROR,
+                    [2] = vim.log.levels.WARN,
+                    [3] = vim.log.levels.INFO,
+                    [4] = vim.log.levels.DEBUG,
+                  }
+                  vim.notify(params.message, message_type[params.type], {
+                    title = "djls",
+                  })
+                end,
+              },
+              on_attach = function(client, bufnr)
+                vim.notify("djls attached to buffer: " .. bufnr)
+              end,
+            },
+          }
+        end
+        require("lspconfig").djls.setup({})
+      end,
+    },
+  },
+}
+```
+
+!!! note
+
+    This configuration is copied straight from my Neovim setup and includes a logging setup that sends LSP messages to Neovim's notification system. You can remove all the references to `vim.notify` if you don't care about this functionality.