Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Reword getting-started.md #303

Merged
merged 1 commit into from
Oct 14, 2022
Merged

Docs: Reword getting-started.md #303

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 20 additions & 25 deletions doc/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,45 +2,41 @@

### 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).
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 [use docker](https://github.com/docat-org/docatl#using-docker).
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.

After you've obtained `docatl` just point it to your docs folder, which will be packaged and pushed to `docat`:
After you've installed `docatl`, just point it to your documentation folder, which will be packaged and pushed to `docat`.
To do this, use the following command:

```sh
docatl push --host http://localhost:8000 ./docs/ awesome-project 1.0.0
```

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

### Raw API endpoints

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

The API specification is exposed as OpenAPI at http://localhost:8000/api/v1/openapi.json
and available with Swagger UI at http://localhost:8000/api/docs and a pure documentation
is available with redoc at http://localhost:8000/api/redoc.
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.

#### Upload your documentation

You can upload any static HTML site by zipping it and
then posting the file to the backend.
You can upload any static HTML page by zipping it and uploading the zip file.

> Note: if a `index.html` file is present in the root of the zip file
it will be server automatically.
> Note: if an `index.html` file is present in the root of the zip file
it will be served automatically.

For example to upload the file `docs.zip` as version `1.0.0` for `awesome-project`.
For example to upload the file `docs.zip` as version `1.0.0` for `awesome-project` using `curl`:

```sh
curl -X POST -F "file=@docs.zip" http://localhost:8000/api/awesome-project/1.0.0
```

Any other file type is uploaded as well.
An uploaded pdf could be viewed like this:
Any file type can be uploaded. To view an uploaded pdf, specify it's full path:

`http://localhost:8000/#/awesome-project/1.0.0/my_awesome.pdf`

Expand All @@ -49,10 +45,10 @@ A very simple web form can be found under [upload](#/upload).

#### Tag documentation

After this you can tag a version, this can be useful when
After uploading you can tag a specific version. This can be useful when
the latest version should be available as `http://localhost:8000/docs/awesome-project/latest`

If you want to tag the version `1.0.0` as `latest` for awesome-project.
To tag the version `1.0.0` as `latest` for `awesome-project`:

```sh
curl -X PUT http://localhost:8000/api/awesome-project/1.0.0/tags/latest
Expand All @@ -61,7 +57,7 @@ curl -X PUT http://localhost:8000/api/awesome-project/1.0.0/tags/latest
#### Claim Project

Claiming a Project returns a `token` which can be used for actions
which require a authentication (for example deleting a version).
which require authentication (for example for deleting a version).
Each Project can be claimed **exactly once**, so best store the token safely.

```sh
Expand All @@ -70,7 +66,7 @@ curl -X GET http://localhost:8000/api/awesome-project/claim

#### Authentication

To make an authenticated call a header with the key `Docat-Api-Key` and your token is required.
To make an authenticated call, specify a header with the key `Docat-Api-Key` and your token as the value:

```sh
curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0
Expand All @@ -80,18 +76,17 @@ curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/aweso

To delete a Project version you need to be authenticated.

If you want to remove the version `1.0.0` from awesome-project.
To remove the version `1.0.0` from `awesome-project`:

```sh
curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0
```

#### Upload Project Icon

To upload a icon, you don't need a token, except if
a project icon already exists.
To upload a icon, you don't need a token, except if you want to replace an existing icon.

If you want to upload `example-image.png` to awesome-project, that already has a project icon.
To set `example-image.png` as the icon for `awesome-project`, which already has an icon:

```sh
curl -X POST -F "file=@example-image.png" --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/icon
Expand Down