From 6f3d6efa2220ab8ad15e3346adc6b7744f07f3e5 Mon Sep 17 00:00:00 2001
From: Keval Kapdee <keval@thechubbypanda.net>
Date: Sun, 5 Jun 2022 22:26:08 +0100
Subject: [PATCH] webiste/docs: Improve clarity of dev environment setup doc
 (#3045)

* Improve clarity of dev environment setup doc

* Requested changes and further small improvements

* I actually read the makefile this time

* Add makefile entry for building ui

* Comments

* Add documentation setup

* Move documentation setup

* Formatting
---
 Makefile                                      |  3 ++
 .../docs/writing-documentation.md             | 18 +++++++++-
 .../setup/full-dev-environment.md             | 35 +++++++++----------
 3 files changed, 36 insertions(+), 20 deletions(-)

diff --git a/Makefile b/Makefile
index 360ce3c7f..1807681ca 100644
--- a/Makefile
+++ b/Makefile
@@ -103,6 +103,9 @@ run:
 ## Web
 #########################
 
+web-build: web-install
+	cd web && npm run build
+
 web: web-lint-fix web-lint web-extract
 
 web-install:
diff --git a/website/developer-docs/docs/writing-documentation.md b/website/developer-docs/docs/writing-documentation.md
index d21b1e26c..7334de1d4 100644
--- a/website/developer-docs/docs/writing-documentation.md
+++ b/website/developer-docs/docs/writing-documentation.md
@@ -5,7 +5,23 @@ title: Writing documentation
 Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. Here are a few guidelines to ensure
 the documentation is easy to read and uses similar phrasing.
 
-# General guidelines
+## Setup
+
+Requirements:
+
+-   Node 16 (or greater)
+
+The documentation site is situated in the `/website` folder of the authentik GitHub repository.
+
+The site is built using npm, below are some useful make commands:
+
+-   Install: `make website-install` (Needed for any of the other tasks)
+-   Formatting: `make website-lint-fix` or `make website` (Run this before committing)
+-   Live editing: `make website-watch` (For real time viewing of changes)
+
+Be sure to run the formatter before committing changes.
+
+## General guidelines
 
 -   authentik should always be stylized as `authentik` (with a lower-case a and ending with a k)
 -   Documentation should use American english
diff --git a/website/developer-docs/setup/full-dev-environment.md b/website/developer-docs/setup/full-dev-environment.md
index b5b22521b..1b4b4269a 100644
--- a/website/developer-docs/setup/full-dev-environment.md
+++ b/website/developer-docs/setup/full-dev-environment.md
@@ -2,21 +2,21 @@
 title: Full development environment
 ---
 
-## Backend
-
-To create a local development setup for authentik, you need the following:
-
-### Requirements
+## Requirements
 
 -   Python 3.10
 -   poetry, which is used to manage dependencies, and can be installed with `pip install poetry`
 -   Go 1.18
 -   PostgreSQL (any recent version will do)
 -   Redis (any recent version will do)
+-   Node 16 (or later)
 
-For PostgreSQL and Redis, you can use the docker-compose file in `scripts/`. You can also use a native install, if you prefer.
+## Services Setup
 
-### Setup
+For PostgreSQL and Redis, you can use the docker-compose file in `scripts/`.  
+You can also use a native install, if you prefer.
+
+## Backend Setup
 
 ```shell
 poetry shell # Creates a python virtualenv, and activates it in a new shell
@@ -36,8 +36,6 @@ secret_key: "A long key you can generate with `pwgen 40 1` for example"
 
 To apply database migrations, run `make migrate`. This is needed after the initial setup, and whenever you fetch new source from upstream.
 
-Afterwards, you can start authentik by running `make run`. authentik is now accessible under `localhost:9000`.
-
 Generally speaking, authentik is a Django application, ran by gunicorn, proxied by a Go application. The Go application serves static files.
 
 Most functions and classes have type-hints and docstrings, so it is recommended to install a Python Type-checking Extension in your IDE to navigate around the code.
@@ -46,18 +44,17 @@ Before committing code, run `make lint` to ensure your code is formatted well. T
 
 Run `make gen` to generate an updated OpenAPI document for any changes you made.
 
-## Frontend
+## Frontend Setup
 
-By default, no compiled bundle of the frontend is included. To build the UI, you need Node 14 or newer.
+By default, no compiled bundle of the frontend is included so this step is required even if you're not developing for the UI.
 
-To build the UI, run these commands:
+To build the UI once, run `web-build`.
 
-```
-cd web/
-npm i
-npm run build
-```
+Alternatively, if you want to live-edit the UI, you can run `make web-watch` instead.  
+This will immediately update the UI with any changes you make so you can see the results in real time without needing to rebuild.
 
-If you want to make changes to the UI, run `npm run watch` instead.
+To format the frontend code, run `make web`.
 
-To ensure the code is formatted well, run `npx eslint . --fix` and `npm run lit-analyse`.
+## Running
+
+Now that the backend and frontend have been setup and built, you can start authentik by running `make run`. authentik should now be accessible at `http://localhost:9000`.