Skip to content

Commit edbb342

Browse files
randombenjrandombenj
committed
Improve documentation
1 parent 5ad819c commit edbb342

File tree

2 files changed

+97
-73
lines changed

2 files changed

+97
-73
lines changed

‎README.md

+72-57
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,22 @@
55
[![build](https://github.com/docat-org/docat/workflows/docat%20ci/badge.svg)](https://github.com/docat-org/docat/actions)
66
[![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)
77

8+
## Why DoCat?
9+
10+
When generating static developer documentation using
11+
[mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/), ...
12+
hosting just one version of the docs might not be enough.
13+
Many users might still use older versions and might need to read
14+
those versions of the documentation.
15+
16+
Docat solves this problem by providing a simple tool that can
17+
host multiple documentation projects with multiple versions.
18+
19+
*The main design decision with docat was to keep the tool as simpel as possible*
20+
821
## Getting started
922

10-
The simplest way is to build and run the docker container,
23+
The simplest way to get started is to run the docker container,
1124
you can optionally use volumes to persist state:
1225

1326
```sh
@@ -25,73 +38,41 @@ Go to [localhost:8000](http://localhost:8000) to view your docat instance:
2538

2639
![docat screenshot](doc/assets/docat-screenshot.png)
2740

28-
### Local Development
41+
### Using DoCat
2942

30-
For local development, first configure and start the backend (inside the `docat/` folder):
31-
32-
```sh
33-
# create a folder for local development (uploading docs)
34-
DEV_DOCAT_PATH="$(mktemp -d)"
43+
> 🛈 Please note that docat does not provide any way to write documentation
44+
> the tool only hosts documentation.
45+
>
46+
> There are many awesome tools to write developer documenation:
47+
> [mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/),
48+
> [mdbook](https://rust-lang.github.io/mdBook/) ...
3549
36-
# install dependencies
37-
poetry install
3850

39-
# run the local development version
40-
DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat
41-
```
51+
A small tool called [docatl](https://github.com/docat-org/docatl) is provided
52+
for easy interaction with the docat server.
53+
However, interacting with docat can also be done through [`curl`](doc/getting-started.md).
4254

43-
After this you need to start the frontend (inside the `web/` folder):
55+
So in order to push documentation (and tag as `latest`) in the folder `docs/` simply run:
4456

4557
```sh
46-
# install dependencies
47-
yarn install --frozen-lockfile
48-
49-
# run the web app
50-
yarn serve
58+
docatl push --host http://localhost:8000 ./docs PROJECT VERSION --tag latest
5159
```
5260

53-
For more advanced options, have a look at the
54-
[backend](docat/README.md) and [web](web/README.md) docs.
61+
More detailed instructions can be found in the [**getting started guide**](doc/getting-started.md).
5562

56-
### Push Documentation to docat
57-
58-
The preferred way to push documentation to a docat server is using the [docatl](https://github.com/docat-org/docatl)
59-
command line application:
60-
61-
```sh
62-
docatl push --host http://localhost:8000 /path/to/your/docs PROJECT VERSION
63-
```
63+
## Authentication
6464

65-
There are also docker images available for CI systems.
65+
By default, anyone can upload new documentation or add a new version to documentation.
66+
A project can be claimed. A claim returns a token that then must be used
67+
to add or delete versions.
6668

67-
#### Using Standard UNIX Command Line Tools
69+
When hosting docat publicly, it is recommended to use
70+
[http basic auth](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)
71+
for all `POST`/`PUT` and `DELETE` http calls.
6872

69-
If you have static html documentation or use something like
70-
[mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/), ...
71-
to generate your documentation, you can push it to docat:
72-
73-
```sh
74-
# create a zip of your docs
75-
zip -r docs.zip /path/to/your-docs
76-
# upload them to the docat server (replace PROJECT/VERSION with your projectname and the version of the docs)
77-
curl -X POST -F "[email protected]" http://localhost:8000/api/PROJECT/VERSION
78-
```
79-
80-
When you have multiple versions you may want to tag some version as **latest**:
81-
82-
```sh
83-
# tag the version VERSION of project PROJECT as latest
84-
curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest
85-
```
73+
## Configuring DoCat
8674

87-
Same thing with `docatl`:
88-
89-
```sh
90-
# tag the version VERSION of project PROJECT as latest
91-
docatl tag --host http://localhost:8000 PROJECT VERSION latest
92-
```
93-
94-
## Advanced Frontend `config.json`
75+
#### Frontend Config
9576

9677
It is possible to configure some things after the fact.
9778

@@ -100,11 +81,45 @@ It is possible to configure some things after the fact.
10081

10182
Supported config options:
10283

103-
- headerHTML
84+
```json
85+
{
86+
"headerHTML": "<h1 style='color: #115fbf;'>Custom Header HTML!</h1>",
87+
}
88+
```
10489

105-
## Advanced System Config
90+
#### System Config
10691

10792
Further proxy configurations can be done through the following environmental variables:
93+
10894
| Variable | Default (Link to Definition) | Description |
10995
|---|---|---|
11096
| MAX_UPLOAD_SIZE | [100M](./Dockerfile) | Limits the size of individual archives posted to the API |
97+
98+
99+
## Local Development
100+
101+
For local development, first configure and start the backend (inside the `docat/` folder):
102+
103+
```sh
104+
# create a folder for local development (uploading docs)
105+
DEV_DOCAT_PATH="$(mktemp -d)"
106+
107+
# install dependencies
108+
poetry install
109+
110+
# run the local development version
111+
DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat
112+
```
113+
114+
After this you need to start the frontend (inside the `web/` folder):
115+
116+
```sh
117+
# install dependencies
118+
yarn install --frozen-lockfile
119+
120+
# run the web app
121+
yarn serve
122+
```
123+
124+
For more advanced options, have a look at the
125+
[backend](docat/README.md) and [web](web/README.md) docs.

‎doc/getting-started.md

+25-16
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,31 @@
1-
## Getting started with DOCAT
1+
## Getting Started with DOCAT
22

3-
### docatl, the docat CLI 🙀
43

5-
The most convenient way to interact with docat is with it's official CLI tool, [docatl](https://github.com/docat-org/docatl).
64

7-
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.
85

9-
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.
6+
### Using `docatl`, the docat CLI 🙀
7+
8+
The most convenient way to interact with docat is with it's official CLI tool,
9+
[docatl](https://github.com/docat-org/docatl).
10+
11+
You can download a standalone binary of the latest release for your platform
12+
[here](https://github.com/docat-org/docatl/releases/latest) or
13+
[use go](https://github.com/docat-org/docatl#using-go) or
14+
[docker](https://github.com/docat-org/docatl#using-docker) to install it.
15+
16+
The commands below contain examples both using `curl` and `docatl`.
17+
Do note that the host address and api-key can be omitted if specified in a `.docatl.yml` file.
18+
See the [docatl documentation](https://github.com/docat-org/docatl/blob/main/README.md) for more information.
1019

1120
Use `docatl --help` to discover all commands available to manage your `docat` documentation!
1221

13-
### Raw API endpoints
22+
### API endpoints
1423

1524
The following sections document the RAW API endpoints you can `curl`.
1625

17-
The API specification is exposed as an OpenAPI Documentation at http://localhost:8000/api/v1/openapi.json,
18-
via Swagger UI at http://localhost:8000/api/docs and
19-
as a pure documentation with redoc at http://localhost:8000/api/redoc.
26+
The API specification is exposed as an [OpenAPI Documentation](/api/v1/openapi.json),
27+
via Swagger UI at [/api/docs](/api/docs) and
28+
as a pure documentation with redoc at [/api/redoc](/api/redoc).
2029

2130
#### Upload your documentation
2231

@@ -31,7 +40,7 @@ For example to upload the file `docs.zip` as version `1.0.0` for `awesome-projec
3140
curl -X POST -F "[email protected]" http://localhost:8000/api/awesome-project/1.0.0
3241
```
3342

34-
Using `docatl`:
43+
Using `docatl`:
3544

3645
```sh
3746
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`:
5564
curl -X PUT http://localhost:8000/api/awesome-project/1.0.0/tags/latest
5665
```
5766

58-
Using `docatl`:
67+
Using `docatl`:
5968

6069
```sh
6170
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.
7180
curl -X GET http://localhost:8000/api/awesome-project/claim
7281
```
7382

74-
Using `docatl`:
83+
Using `docatl`:
7584

7685
```sh
7786
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
8594
curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0
8695
```
8796

88-
Using `docatl`:
97+
Using `docatl`:
8998

9099
```sh
91100
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`:
101110
curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0
102111
```
103112

104-
Using `docatl`:
113+
Using `docatl`:
105114

106115
```sh
107116
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
117126
curl -X POST -F "[email protected]" --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/icon
118127
```
119128

120-
Using `docatl`:
129+
Using `docatl`:
121130

122131
```sh
123132
docatl push-icon awesome-project example-image.png --host http://localhost:8000 --api-key <token>
@@ -170,4 +179,4 @@ Using `docatl`:
170179

171180
```sh
172181
docatl show awesome-project 0.0.1 --host http://localhost:8000 --api-key <token>
173-
```
182+
```

0 commit comments

Comments
 (0)