Move the documentation to the website

Author: eikendev

.github/workflows/main.yml

@@ -15,6 +15,14 @@ jobs:
         with:
           fetch-depth: 0 # Hugo uses Git information to fetch .Lastmod information (enableGitInfo).
 
+      - name: Setup Python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+
       - name: Build
         run: make build
 

.gitignore

@@ -117,3 +117,143 @@ dist
 # Stores VSCode versions used for testing VSCode extensions
 .vscode-test
 
+### Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+

Makefile

@@ -10,6 +10,8 @@ dependencies:
 .PHONY: build
 build: dependencies
 	./hugo --minify
+	cd docs && make build
+	mv ./docs/site ./public/docs
 	# If we run using Docker, we should reset file ownership afterwards.
 ifneq (,$(findstring docker,${ENGINE_COMMAND}))
 	sudo chown -R ${shell id -u ${USER}}:${shell id -g ${USER}} ./public/

docs/.gitignore

@@ -0,0 +1 @@
+site/

docs/Makefile

@@ -0,0 +1,14 @@
+.PHONY: all
+all: build
+
+.PHONY: build
+build:
+	mkdocs build
+
+.PHONY: server
+server:
+	mkdocs serve
+
+.PHONY: clean
+clean:
+	rm -rf ./site/

docs/docs/assets/favicon.ico

@@ -0,0 +1,3 @@
+# Developer Guide
+
+_This site is under construction._

docs/docs/assets/logo.svg

@@ -0,0 +1,105 @@
+# Getting Started
+
+## Installation
+
+PushBits is meant to be self-hosted.
+That means you have to install it on your own server.
+You are advised to install PushBits behind a reverse proxy and enable TLS.
+
+Currently, the only supported way of installing PushBits is via [Docker](https://www.docker.com/) or [Podman](https://podman.io/).
+The image is hosted [via ghcr.io](https://github.com/pushbits/server/pkgs/container/server).
+
+## Configuration
+
+To see what can be configured, have a look at the [config.sample.yml](https://github.com/pushbits/server/blob/master/config.example.yml) file inside the root of the repository.
+
+Settings can optionally be provided via environment variables.
+The name of the environment variable is composed of a starting `PUSHBITS_`, followed by the keys of the setting, all
+joined with `_`.
+As an example, the HTTP port can be provided as an environment variable called `PUSHBITS_HTTP_PORT`.
+
+To get started, here is a Docker Compose file you can use.
+```yaml
+version: '2'
+
+services:
+    server:
+        image: ghcr.io/pushbits/server:latest
+        ports:
+            - 8080:8080
+        environment:
+            PUSHBITS_DATABASE_DIALECT: 'sqlite3'
+            PUSHBITS_ADMIN_MATRIXID: '@your/matrix/username:matrix.org' # The Matrix account on which the admin will receive their notifications.
+            PUSHBITS_ADMIN_PASSWORD: 'your/pushbits/password' # The login password of the admin account. Default username is 'admin'.
+            PUSHBITS_MATRIX_USERNAME: 'your/matrix/username' # The Matrix account from which notifications are sent to all users.
+            PUSHBITS_MATRIX_PASSWORD: 'your/matrix/password' # The password of the above account.
+        volumes:
+            - /etc/localtime:/etc/localtime:ro
+            - /etc/timezone:/etc/timezone:ro
+            - ./data:/data
+```
+
+In this example, the configuration file would be located at `./data/config.yml` on the host.
+The SQLite database would be written to `./data/pushbits.db`.
+**Don't forget to adjust the permissions** of the `./data` directory, otherwise PushBits will fail to operate.
+
+## Usage
+
+We provide [a little CLI tool called pbcli](https://github.com/PushBits/cli) to make basic API requests to the server.
+It helps you to create new users and applications.
+You will find further instructions in the linked repository.
+
+At the time of writing, there is no fancy GUI built-in, and we're not sure if this is necessary at all.
+Currently, we would like to avoid front end development, so if you want to contribute in this regard we're happy if you reach out!
+
+After you have created a user and an application, you can use the API to send a push notification to your Matrix account.
+
+```bash
+curl \
+	--header "Content-Type: application/json" \
+	--request POST \
+	--data '{"message":"my message","title":"my title"}' \
+	"https://pushbits.example.com/message?token=$PB_TOKEN"
+```
+
+Note that the token is associated with your application and has to be kept secret.
+You can retrieve the token using [pbcli](https://github.com/PushBits/cli) by running following command.
+
+```bash
+pbcli application show $PB_APPLICATION --url https://pushbits.example.com --username $PB_USERNAME
+```
+
+### Message options
+
+Messages can be specified in three different syntaxes:
+
+* `text/plain`
+* `text/html`
+* `text/markdown`
+
+To set a specific syntax you need to set the `extras` parameter ([inspired by Gotify's message extras](https://gotify.net/docs/msgextras#clientdisplay)):
+
+```bash
+curl \
+	--header "Content-Type: application/json" \
+	--request POST \
+	--data '{"message":"my message with\n\n**Markdown** _support_.","title":"my title","extras":{"client::display":{"contentType": "text/markdown"}}}' \
+	"https://pushbits.example.com/message?token=$PB_TOKEN"
+```
+
+HTML content might not be fully rendered in your Matrix client; see the corresponding [Matrix specs](https://spec.matrix.org/unstable/client-server-api/#mroommessage-msgtypes).
+This also holds for Markdown, as it is translated into the corresponding HTML syntax.
+
+### Deleting a Message
+
+You can delete a message, this will send a notification in response to the original message informing you that the message is "deleted".
+
+To delete a message, you need its message ID  which is provided as part of the response when you send the message.
+The ID might contain characters not valid in URIs.
+We hence provide an additional `id_url_encoded` field for messages; you can directly use it when deleting a message without performing encoding yourself.
+
+```bash
+curl \
+	--request DELETE \
+	"https://pushbits.example.com/message/${MESSAGE_ID}?token=$PB_TOKEN"
+```

docs/docs/developer-guide.md

@@ -0,0 +1,3 @@
+# User Guide
+
+_This site is under construction._