Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@randombenj
randombenj committed Oct 15, 2024
1 parent 561e02e commit bca4227
Show file tree
Hide file tree
Showing 2 changed files with 97 additions and 73 deletions.
129 changes: 72 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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.
41 changes: 25 additions & 16 deletions doc/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -170,4 +179,4 @@ Using `docatl`:

```sh
docatl show awesome-project 0.0.1 --host http://localhost:8000 --api-key <token>
```
```

0 comments on commit bca4227

Please sign in to comment.