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 developer 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 can
+host multiple documentation projects with multiple versions.
+
+*The main design decision with docat was to keep the tool as simpel 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,75 +36,43 @@ 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):
-
-```sh
-# create a folder for local development (uploading docs)
-DEV_DOCAT_PATH="$(mktemp -d)"
+> 🛈 Please note that docat does not provide any way to write documentation
+> the tool only hosts documentation.
+>
+> There are many awesome tools to write developer documenation:
+> [mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/),
+> [mdbook](https://rust-lang.github.io/mdBook/) ...
 
-# install dependencies
-poetry install
 
-# run the local development version
-DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat
-```
+A small tool called [docatl](https://github.com/docat-org/docatl) is provided
+for easy interaction with the docat server.
+However, interacting with docat can also be done through [`curl`](doc/getting-started.md).
 
-After this you need to start the frontend (inside the `web/` folder):
+So in order to push documentation (and tag as `latest`) in the folder `docs/` simply run:
 
 ```sh
-# install dependencies
-yarn install --frozen-lockfile
-
-# run the web app
-yarn serve
+docatl push --host http://localhost:8000 ./docs PROJECT VERSION --tag latest
 ```
 
-For more advanced options, have a look at the
-[backend](docat/README.md) and [web](web/README.md) docs.
+More detailed instructions can be found in the [**getting started guide**](doc/getting-started.md).
 
-### Push Documentation to docat
-
-The preferred way to push documentation to a docat server is using the [docatl](https://github.com/docat-org/docatl)
-command line application:
-
-```sh
-docatl push --host http://localhost:8000 /path/to/your/docs PROJECT VERSION
-```
+## Authentication
 
-There are also docker images available for CI systems.
+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.
 
-#### Using Standard UNIX Command Line Tools
+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.
 
-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:
-
-```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 "file=@docs.zip" http://localhost:8000/api/PROJECT/VERSION
-```
-
-When you have multiple versions you may want to tag some version as **latest**:
-
-```sh
-# tag the version VERSION of project PROJECT as latest
-curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest
-```
+## Configuring DoCat
 
-Same thing with `docatl`:
-
-```sh
-# tag the version VERSION of project PROJECT as latest
-docatl tag --host http://localhost:8000 PROJECT VERSION latest
-```
-
-## Advanced Frontend `config.json`
+#### Frontend Config
 
 It is possible to configure some things after the fact.
 
@@ -100,11 +81,45 @@ It is possible to configure some things after the fact.
 
 Supported config options:
 
-- headerHTML
+```json
+{
+  "headerHTML": "<h1 style='color: #115fbf;'>Custom Header HTML!</h1>",
+}
+```
 
-## Advanced System Config
+#### System Config
 
 Further proxy configurations can be done through the following environmental variables:
+
 | Variable | Default (Link to Definition) | Description |
 |---|---|---|
 | 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 "file=@docs.zip" 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 "file=@example-image.png" --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/docat/app.py

@@ -22,7 +22,7 @@
 from starlette.responses import JSONResponse
 from tinydb import Query, TinyDB
 
-from docat.models import ApiResponse, ClaimResponse, ProjectDetail, Projects, TokenStatus
+from docat.models import ApiResponse, ClaimResponse, ProjectDetail, Projects, Stats, TokenStatus
 from docat.utils import (
     DB_PATH,
     UPLOAD_FOLDER,
@@ -31,6 +31,7 @@
     extract_archive,
     get_all_projects,
     get_project_details,
+    get_system_stats,
     is_forbidden_project_name,
     remove_docs,
 )
@@ -65,6 +66,13 @@ def get_db() -> TinyDB:
 )
 
 
+@app.get("/api/stats", response_model=Stats, status_code=status.HTTP_200_OK)
+def get_stats():
+    if not DOCAT_UPLOAD_FOLDER.exists():
+        return Projects(projects=[])
+    return get_system_stats(DOCAT_UPLOAD_FOLDER)
+
+
 @app.get("/api/projects", response_model=Projects, status_code=status.HTTP_200_OK)
 def get_projects(include_hidden: bool = False):
     if not DOCAT_UPLOAD_FOLDER.exists():

docat/docat/models.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from datetime import datetime
 
 from pydantic import BaseModel
 
@@ -19,20 +20,29 @@ class ClaimResponse(ApiResponse):
 
 class ProjectVersion(BaseModel):
     name: str
+    timestamp: datetime
     tags: list[str]
     hidden: bool
 
 
 class Project(BaseModel):
     name: str
     logo: bool
+    storage: str
     versions: list[ProjectVersion]
 
 
 class Projects(BaseModel):
     projects: list[Project]
 
 
+class Stats(BaseModel):
+    n_projects: int
+    n_versions: int
+    storage: str
+
+
 class ProjectDetail(BaseModel):
     name: str
+    storage: str
     versions: list[ProjectVersion]