WIP: Develop docs

Makefile

@@ -4,37 +4,47 @@ VERSION := $(shell git describe --tag)
 
 help:
 	@echo "Typical commands:"
-	@echo "  make check                       - Run all tests, vetting/formatting checks and linters"
+	@echo "  make check                   - Run all tests, vetting/formatting checks and linters"
-	@echo "  make fmt build-snapshot install  - Build latest and install to local system"
+	@echo "  make build-snapshot install  - Build latest and install to local system"
 	@echo
 	@echo "Test/check:"
-	@echo "  make test                        - Run tests"
+	@echo "  make test                    - Run tests"
-	@echo "  make race                        - Run tests with -race flag"
+	@echo "  make race                    - Run tests with -race flag"
-	@echo "  make coverage                    - Run tests and show coverage"
+	@echo "  make coverage                - Run tests and show coverage"
-	@echo "  make coverage-html               - Run tests and show coverage (as HTML)"
+	@echo "  make coverage-html           - Run tests and show coverage (as HTML)"
-	@echo "  make coverage-upload             - Upload coverage results to codecov.io"
+	@echo "  make coverage-upload         - Upload coverage results to codecov.io"
 	@echo
 	@echo "Lint/format:"
-	@echo "  make fmt                         - Run 'go fmt'"
+	@echo "  make fmt                     - Run 'go fmt'"
-	@echo "  make fmt-check                   - Run 'go fmt', but don't change anything"
+	@echo "  make fmt-check               - Run 'go fmt', but don't change anything"
-	@echo "  make vet                         - Run 'go vet'"
+	@echo "  make vet                     - Run 'go vet'"
-	@echo "  make lint                        - Run 'golint'"
+	@echo "  make lint                    - Run 'golint'"
-	@echo "  make staticcheck                 - Run 'staticcheck'"
+	@echo "  make staticcheck             - Run 'staticcheck'"
 	@echo
-	@echo "Build:"
+	@echo "Build main client/server:"
-	@echo "  make build                       - Build"
+	@echo "  make build                   - Build (using goreleaser, requires clean repo)"
-	@echo "  make build-snapshot              - Build snapshot"
+	@echo "  make build-snapshot          - Build snapshot (using goreleaser, dirty repo)"
-	@echo "  make build-simple                - Build (using go build, without goreleaser)"
+	@echo "  make build-simple            - Quick & dirty build (using go build, without goreleaser)"
-	@echo "  make clean                       - Clean build folder"
+	@echo "  make clean                   - Clean build folder"
+	@echo
+	@echo "Build web app:"
+	@echo "  make web                     - Build the web app"
+	@echo "  make web-deps                - Install web app dependencies (npm install the universe)"
+	@echo "  make web-build               - Actually build the web app"
+	@echo
+	@echo "Build documentation:"
+	@echo "  make docs                     - Build the documentation"
+	@echo "  make docs-deps                - Install Python dependencies (pip3 install)"
+	@echo "  make docs-build               - Actually build the documentation"
 	@echo
 	@echo "Releasing (requires goreleaser):"
-	@echo "  make release                     - Create a release"
+	@echo "  make release                 - Create a release"
-	@echo "  make release-snapshot            - Create a test release"
+	@echo "  make release-snapshot        - Create a test release"
 	@echo
 	@echo "Install locally (requires sudo):"
-	@echo "  make install                     - Copy binary from dist/ to /usr/bin"
+	@echo "  make install                 - Copy binary from dist/ to /usr/bin"
-	@echo "  make install-deb                 - Install .deb from dist/"
+	@echo "  make install-deb             - Install .deb from dist/"
-	@echo "  make install-lint                - Install golint"
+	@echo "  make install-lint            - Install golint"
 
 
 # Documentation
@@ -42,9 +52,11 @@ help:
 docs-deps: .PHONY
 	pip3 install -r requirements.txt
 
-docs: docs-deps
+docs-build: .PHONY
 	mkdocs build
 
+docs: docs-deps docs-build
+
 
 # Web app
 
@@ -126,7 +138,7 @@ build: build-deps
 build-snapshot: build-deps
 	goreleaser build --snapshot --rm-dist --debug
 
-build-simple: clean
+build-simple: .PHONY
 	mkdir -p dist/ntfy_linux_amd64 server/docs server/site
 	touch server/docs/index.html
 	touch server/site/app.html

docs/develop.md

@@ -1,16 +1,72 @@
 # Building
 
+!!! info
+    These instructions are pretty rough. My apologies for that. Please help improve them my letting me 
+    know in a [GitHub issue](https://github.com/binwiederhier/ntfy/issues).
+
 ## ntfy server
-The ntfy server source code is available [on GitHub](https://github.com/binwiederhier/ntfy). 
+The ntfy server source code is available [on GitHub](https://github.com/binwiederhier/ntfy). The codebase for the
+server consists of three components:
+
+* **The main server and API** is written in [Go](https://go.dev/) (so you'll need Go). Its main entrypoint is at 
+  [main.go](https://github.com/binwiederhier/ntfy/blob/main/main.go), and the meat you're likely interested in is 
+  in [server.go](https://github.com/binwiederhier/ntfy/blob/main/server/server.go). Notably, the server uses a 
+  [SQLite](https://sqlite.org) library called [go-sqlite3](https://github.com/mattn/go-sqlite3), which requires 
+  [Cgo](https://go.dev/blog/cgo) and `CGO_ENABLED=1` to be set. Otherwise things will not work (see below).
+* **The documentation** is generated by [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
+  which is written in [Python](https://www.python.org/). You'll need Python and MkDocs (via `pip`) only if you want to
+  build the docs.
+* **The web app** is written in [React](https://reactjs.org/), using [MUI](https://mui.com/). If you want to modify the 
+  web app, you need [nodejs](https://nodejs.org/en/) (for `npm`) to install all the 100,000 dependencies (*sigh*).
+
+All of these components are built and then **baked into one binary**. 
+
+### Requirements
+
+* [Go](https://go.dev/) (required for main server)
+* [gcc](https://gcc.gnu.org/) (required main server, for SQLite cgo-based bindings)
+* [Make](https://www.gnu.org/software/make/) (required for convenience)
+* [libsqlite3/libsqlite3-dev](https://www.sqlite.org/) (required for main server, for SQLite cgo-based bindings)
+* [GoReleaser](https://goreleaser.com/) (required for a proper main server build)
+* [Python](https://www.python.org/) (for `pip`, only to build the docs) 
+* [nodejs](https://nodejs.org/en/) (for `npm`, only to build the web app)
+
+### Check out the code & install dependencies
+Check out via git:
+
+=== "via SSH"
+    ```
+    git clone git@github.com:binwiederhier/ntfy.git 
+    cd ntfy
+    ```
+=== "via HTTPS"
+    ```
+    git clone https://github.com/binwiederhier/ntfy.git
+    cd ntfy
+    ```
+
+Then install the dependencies (this assumes Debian/Ubuntu):
+
+```
+sudo apt install build-essential libsqlite3-dev
+```
+
+To install Python/NodeJS (for docs and web app), please see instructions on their websites.
+
+### 
+
+XXXXXXXXXXXXXXXXXXXXx
+
+
+### Quick & dirty (amd64 only)
 To quickly build on amd64, you can use `make build-simple`:
 
 ```
-git clone git@github.com:binwiederhier/ntfy.git
-cd ntfy
 make build-simple
 ```
 
-That'll generate a statically linked binary in `dist/ntfy_linux_amd64/ntfy`.
+That'll generate a statically linked binary in `dist/ntfy_linux_amd64/ntfy`. This binary will **not include the docs
+or the web app**. To include that
 
 For all other platforms (including Docker), and for production or other snapshot builds, you should use the amazingly 
 awesome [GoReleaser](https://goreleaser.com/) make targets:
@@ -39,7 +95,7 @@ The Android app has two flavors:
 First check out the repository:
 
 ```
-git clone git@github.com:binwiederhier/ntfy-android.git
+git clone git@github.com:binwiederhier/ntfy-android.git   # or: https://github.com/binwiederhier/ntfy-android.git
 cd ntfy-android
 ```