From 5b10f51af1f9c17ae9d92c69d446744b875bfa6a Mon Sep 17 00:00:00 2001 From: Philipp Heckel <pheckel@datto.com> Date: Wed, 16 Mar 2022 22:33:23 -0400 Subject: [PATCH] WIP: Develop docs --- Makefile | 60 ++++++++++++++++++++++++++------------------ docs/develop.md | 66 +++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 97 insertions(+), 29 deletions(-) diff --git a/Makefile b/Makefile index 3bd40ea..7fe4b46 100644 --- a/Makefile +++ b/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 fmt build-snapshot install - Build latest and install to local system" + @echo " make check - Run all tests, vetting/formatting checks and linters" + @echo " make build-snapshot install - Build latest and install to local system" @echo @echo "Test/check:" - @echo " make test - Run tests" - @echo " make race - Run tests with -race flag" - @echo " make coverage - Run tests and show coverage" - @echo " make coverage-html - Run tests and show coverage (as HTML)" - @echo " make coverage-upload - Upload coverage results to codecov.io" + @echo " make test - Run tests" + @echo " make race - Run tests with -race flag" + @echo " make coverage - Run tests and show coverage" + @echo " make coverage-html - Run tests and show coverage (as HTML)" + @echo " make coverage-upload - Upload coverage results to codecov.io" @echo @echo "Lint/format:" - @echo " make fmt - Run 'go fmt'" - @echo " make fmt-check - Run 'go fmt', but don't change anything" - @echo " make vet - Run 'go vet'" - @echo " make lint - Run 'golint'" - @echo " make staticcheck - Run 'staticcheck'" + @echo " make fmt - Run 'go fmt'" + @echo " make fmt-check - Run 'go fmt', but don't change anything" + @echo " make vet - Run 'go vet'" + @echo " make lint - Run 'golint'" + @echo " make staticcheck - Run 'staticcheck'" @echo - @echo "Build:" - @echo " make build - Build" - @echo " make build-snapshot - Build snapshot" - @echo " make build-simple - Build (using go build, without goreleaser)" - @echo " make clean - Clean build folder" + @echo "Build main client/server:" + @echo " make build - Build (using goreleaser, requires clean repo)" + @echo " make build-snapshot - Build snapshot (using goreleaser, dirty repo)" + @echo " make build-simple - Quick & dirty build (using go build, without goreleaser)" + @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-snapshot - Create a test release" + @echo " make release - Create a 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-deb - Install .deb from dist/" - @echo " make install-lint - Install golint" + @echo " make install - Copy binary from dist/ to /usr/bin" + @echo " make install-deb - Install .deb from dist/" + @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 diff --git a/docs/develop.md b/docs/develop.md index 99ba688..a35b403 100644 --- a/docs/develop.md +++ b/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 ``` -- GitLab