Merge pull request #907 from docat-org/feature/redesign-front-page

Redesign front page

README.md

@@ -5,9 +5,22 @@
 [![build](https://github.com/docat-org/docat/workflows/docat%20ci/badge.svg)](https://github.com/docat-org/docat/actions)
 [![Gitter](https://badges.gitter.im/docat-docs-hosting/community.svg)](https://gitter.im/docat-docs-hosting/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
+## Why DOCAT?
+
+When generating static documentation using
+[mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/), ...
+hosting just one version of the docs might not be enough.
+Many users might still use older versions and might need to read
+those versions of the documentation.
+
+Docat solves this problem by providing a simple tool that
+hosts multiple documentation projects with multiple versions.
+
+*The main design decision with docat was to keep the tool as simple as possible.*
+
 ## Getting started
 
-The simplest way is to build and run the docker container,
+The simplest way to get started is to run the docker container,
 you can optionally use volumes to persist state:
 
 ```sh
@@ -23,88 +36,151 @@ docker run \
 
 Go to [localhost:8000](http://localhost:8000) to view your docat instance:
 
-![docat screenshot](doc/assets/docat-screenshot.png)
+<img src="doc/assets/docat.gif" width="100%" />
 
-### Local Development
+### Using DOCAT
 
-For local development, first configure and start the backend (inside the `docat/` folder):
+> 🛈 Please note that docat does not provide any way to write documentation.
+> It's sole responsibility is to host documentation.
+>
+> There are many awesome tools to write documenation:
+> - [mkdocs](https://www.mkdocs.org/)
+> - [sphinx](http://www.sphinx-doc.org/en/master/)
+> - [mdbook](https://rust-lang.github.io/mdBook/)
+> - ...
 
-```sh
-# create a folder for local development (uploading docs)
-DEV_DOCAT_PATH="$(mktemp -d)"
 
-# install dependencies
-poetry install
+A CLI tool called [docatl](https://github.com/docat-org/docatl) is available
+for easy interaction with the docat server.
+However, interacting with docat can also be done through [`curl`](doc/getting-started.md).
 
-# run the local development version
-DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat
+To push documentation (and tag as `latest`) in the folder `docs/` simply run:
+
+```sh
+docatl push --host http://localhost:8000 ./docs PROJECT VERSION --tag latest
 ```
 
-After this you need to start the frontend (inside the `web/` folder):
+More detailed instructions can be found in the [**getting started guide**](doc/getting-started.md).
 
-```sh
-# install dependencies
-yarn install --frozen-lockfile
+## Authentication
 
-# run the web app
-yarn serve
-```
+By default, anyone can upload new documentation or add a new version to documentation.
+A project can be claimed. A claim returns a token that then must be used
+to add or delete versions.
 
-For more advanced options, have a look at the
-[backend](docat/README.md) and [web](web/README.md) docs.
+When hosting docat publicly, it is recommended to use
+[http basic auth](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)
+for all `POST`/`PUT` and `DELETE` http calls.
 
-### Push Documentation to docat
+<details>
+  <summary>docat http basic authentication example</summary>
 
-The preferred way to push documentation to a docat server is using the [docatl](https://github.com/docat-org/docatl)
-command line application:
+This example shows how to configure the NGINX inside the docker image
+to be password protected using http basic auth.
 
-```sh
-docatl push --host http://localhost:8000 /path/to/your/docs PROJECT VERSION
-```
+1) Create your [`.htpasswd` file](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/#creating-a-password-file).
+2) And a custom `default` NGINX config:
 
-There are also docker images available for CI systems.
+  ```
+  upstream python_backend {
+      server 127.0.0.1:5000;
+  }
 
-#### Using Standard UNIX Command Line Tools
+  server {
+      listen 80 default_server;
+      listen [::]:80 default_server;
 
-If you have static html documentation or use something like
-[mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/), ...
-to generate your documentation, you can push it to docat:
+      root /var/www/html;
 
-```sh
-# create a zip of your docs
-zip -r docs.zip /path/to/your-docs
-# upload them to the docat server (replace PROJECT/VERSION with your projectname and the version of the docs)
-curl -X POST -F "[email protected]" http://localhost:8000/api/PROJECT/VERSION
-```
+      add_header Content-Security-Policy "frame-ancestors 'self';";
+      index index.html index.htm index.pdf /index.html;
 
-When you have multiple versions you may want to tag some version as **latest**:
+      server_name _;
 
-```sh
-# tag the version VERSION of project PROJECT as latest
-curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest
-```
+      location /doc {
+          root /var/docat;
+      }
 
-Same thing with `docatl`:
+      location /api {
+          limit_except GET HEAD {
+              auth_basic 'Restricted';
+              auth_basic_user_file /etc/nginx/.htpasswd;
+          }
 
-```sh
-# tag the version VERSION of project PROJECT as latest
-docatl tag --host http://localhost:8000 PROJECT VERSION latest
-```
+          client_max_body_size $MAX_UPLOAD_SIZE;
+          proxy_pass http://python_backend;
+      }
+
+      location / {
+          try_files $uri $uri/ =404;
+      }
+  }
+  ```
 
-## Advanced Frontend `config.json`
+1) Mounted to the correct location inside the container:
+
+  ```
+  docker run \
+    --detach \
+    --volume $PWD/docat-run:/var/docat/ \
+    --volume $PWD/nginx/default:/app/docat/docat/nginx/default \
+    --volume $PWD/nginx/.htpasswd:/etc/nginx/.htpasswd \
+    --publish 8000:80 \
+    ghcr.io/docat-org/docat
+  ```
+</details>
+
+## Configuring DOCAT
+
+#### Frontend Config
 
 It is possible to configure some things after the fact.
 
 1. Create a `config.json` file
-2. Mount it inside your docker container `--volume /path/to/config.json:/var/docat/doc/config.json`
+2. Mount it inside your docker container `--volume $PWD/config.json:/var/docat/doc/config.json`
 
 Supported config options:
 
-- headerHTML
+```json
+{
+  "headerHTML": "<h1 style='color: #115fbf;'>Custom Header HTML!</h1>",
+  "footerHTML": "CONTACT: <a href='mailto:[email protected]'>Maintainers</a>"
+}
+```
 
-## Advanced System Config
+#### System Config
 
 Further proxy configurations can be done through the following environmental variables:
-| Variable | Default (Link to Definition) | Description |
+
+| Variable | Default | Description |
 |---|---|---|
-| MAX_UPLOAD_SIZE | [100M](./Dockerfile) | Limits the size of individual archives posted to the API |
+| `MAX_UPLOAD_SIZE` | [100M](./Dockerfile) | Limits the size of individual archives posted to the API |
+
+
+## Local Development
+
+For local development, first configure and start the backend (inside the `docat/` folder):
+
+```sh
+# create a folder for local development (uploading docs)
+DEV_DOCAT_PATH="$(mktemp -d)"
+
+# install dependencies
+poetry install
+
+# run the local development version
+DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat
+```
+
+After this you need to start the frontend (inside the `web/` folder):
+
+```sh
+# install dependencies
+yarn install --frozen-lockfile
+
+# run the web app
+yarn serve
+```
+
+For more advanced options, have a look at the
+[backend](docat/README.md) and [web](web/README.md) docs.

doc/getting-started.md

@@ -1,22 +1,31 @@
-## Getting started with DOCAT
+## Getting Started with DOCAT
 
-### docatl, the docat CLI 🙀
 
-The most convenient way to interact with docat is with it's official CLI tool, [docatl](https://github.com/docat-org/docatl).
 
-You can download a standalone binary of the latest release for your platform [here](https://github.com/docat-org/docatl/releases/latest) or [use go](https://github.com/docat-org/docatl#using-go) or [docker](https://github.com/docat-org/docatl#using-docker) to install it.
 
-The commands below contain examples both using `curl` and `docatl`. Do note that the host address and api-key can be omitted if specified in a `.docatl.yml` file. See the [docatl documentation](https://github.com/docat-org/docatl/blob/main/README.md) for more information.
+### Using `docatl`, the docat CLI 🙀
+
+The most convenient way to interact with docat is with it's official CLI tool,
+[docatl](https://github.com/docat-org/docatl).
+
+You can download a standalone binary of the latest release for your platform
+[here](https://github.com/docat-org/docatl/releases/latest) or
+[use go](https://github.com/docat-org/docatl#using-go) or
+[docker](https://github.com/docat-org/docatl#using-docker) to install it.
+
+The commands below contain examples both using `curl` and `docatl`.
+Do note that the host address and api-key can be omitted if specified in a `.docatl.yml` file.
+See the [docatl documentation](https://github.com/docat-org/docatl/blob/main/README.md) for more information.
 
 Use `docatl --help` to discover all commands available to manage your `docat` documentation!
 
-### Raw API endpoints
+### API endpoints
 
 The following sections document the RAW API endpoints you can `curl`.
 
-The API specification is exposed as an OpenAPI Documentation at http://localhost:8000/api/v1/openapi.json, 
-via Swagger UI at http://localhost:8000/api/docs and 
-as a pure documentation with redoc at http://localhost:8000/api/redoc.
+The API specification is exposed as an [OpenAPI Documentation](/api/v1/openapi.json),
+via Swagger UI at [/api/docs](/api/docs) and
+as a pure documentation with redoc at [/api/redoc](/api/redoc).
 
 #### Upload your documentation
 
@@ -31,7 +40,7 @@ For example to upload the file `docs.zip` as version `1.0.0` for `awesome-projec
 curl -X POST -F "[email protected]" http://localhost:8000/api/awesome-project/1.0.0
 ```
 
-Using `docatl`: 
+Using `docatl`:
 
 ```sh
 docatl push docs.zip awesome-project 1.0.0 --host http://localhost:8000
@@ -55,7 +64,7 @@ To tag the version `1.0.0` as `latest` for `awesome-project`:
 curl -X PUT http://localhost:8000/api/awesome-project/1.0.0/tags/latest
 ```
 
-Using `docatl`: 
+Using `docatl`:
 
 ```sh
 docatl tag awesome-project 1.0.0 latest --host http://localhost:8000
@@ -71,7 +80,7 @@ Each Project can be claimed **exactly once**, so best store the token safely.
 curl -X GET http://localhost:8000/api/awesome-project/claim
 ```
 
-Using `docatl`: 
+Using `docatl`:
 
 ```sh
 docatl claim awesome-project --host http://localhost:8000
@@ -85,7 +94,7 @@ To make an authenticated call, specify a header with the key `Docat-Api-Key` and
 curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0
 ```
 
-Using `docatl`: 
+Using `docatl`:
 
 ```sh
 docatl delete awesome-project 1.0.0 --host http://localhost:8000 --api-key <token>
@@ -101,7 +110,7 @@ To remove the version `1.0.0` from `awesome-project`:
 curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0
 ```
 
-Using `docatl`: 
+Using `docatl`:
 
 ```sh
 docatl delete awesome-project 1.0.0 --host http://localhost:8000 --api-key <token>
@@ -117,7 +126,7 @@ To set `example-image.png` as the icon for `awesome-project`, which already has
 curl -X POST -F "[email protected]" --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/icon
 ```
 
-Using `docatl`: 
+Using `docatl`:
 
 ```sh
 docatl push-icon awesome-project example-image.png --host http://localhost:8000 --api-key <token>
@@ -170,4 +179,4 @@ Using `docatl`:
 
 ```sh
 docatl show awesome-project 0.0.1 --host http://localhost:8000 --api-key <token>
-```
+```

docat/Makefile

@@ -1,7 +1,12 @@
+.PHONY: all
+all: format lint typing pytest
+
 format:
 	poetry run ruff check --fix
 	poetry run ruff format
 lint:
 	poetry run ruff check
+typing:
+	poetry run mypy .
 pytest:
 	poetry run pytest