diff --git a/README.md b/README.md index 2cf93c124..62cb96c4b 100644 --- a/README.md +++ b/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 @@ -25,73 +38,41 @@ Go to [localhost:8000](http://localhost:8000) to view your docat instance: ![docat screenshot](doc/assets/docat-screenshot.png) -### 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": "

Custom Header HTML!

", +} +``` -## 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. diff --git a/doc/getting-started.md b/doc/getting-started.md index 232aa78c9..3656f91f1 100644 --- a/doc/getting-started.md +++ b/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: " 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 @@ -101,7 +110,7 @@ To remove the version `1.0.0` from `awesome-project`: curl -X DELETE --header "Docat-Api-Key: " 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 @@ -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: " 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 @@ -170,4 +179,4 @@ Using `docatl`: ```sh docatl show awesome-project 0.0.1 --host http://localhost:8000 --api-key -``` \ No newline at end of file +```