From 5dac650c52810348aaf148236639b24e781712a9 Mon Sep 17 00:00:00 2001 From: reglim Date: Mon, 17 Oct 2022 09:18:06 +0200 Subject: [PATCH 1/2] Docs: Add docatl command examples as alternatives to curl fixes: #312 --- README.md | 7 +++++++ doc/getting-started.md | 43 ++++++++++++++++++++++++++++++++++++------ 2 files changed, 44 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e3db4f3fe..232cf6d59 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,13 @@ When you have multiple versions you may want to tag some version as **latest**: curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest ``` +Same thing with `docatl`: + +```sh +# tag the version VERSION of project PROJECT as latest +docatl tag --host http://localhost:8000 PROJECT VERSION +``` + ## Advanced `config.json` It is possible to configure some things after the fact. diff --git a/doc/getting-started.md b/doc/getting-started.md index 93d767e3e..8df7841db 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -6,12 +6,7 @@ The most convenient way to interact with docat is with it's official CLI tool, [ 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 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 -``` +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! @@ -36,6 +31,12 @@ 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`: + +```sh +docatl push docs.zip awesome-project 1.0.0 --host http://localhost:8000 +``` + 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` @@ -54,6 +55,12 @@ 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`: + +```sh +docatl tag awesome-project 1.0.0 latest --host http://localhost:8000 +``` + #### Claim Project Claiming a Project returns a `token` which can be used for actions @@ -64,6 +71,12 @@ 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`: + +```sh +docatl claim awesome-project --host http://localhost:8000 +``` + #### Authentication To make an authenticated call, specify a header with the key `Docat-Api-Key` and your token as the value: @@ -72,6 +85,12 @@ 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`: + +```sh +docatl delete awesome-project 1.0.0 --host http://localhost:8000 --api-key +``` + #### Delete Version To delete a Project version you need to be authenticated. @@ -82,6 +101,12 @@ 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`: + +```sh +docatl delete awesome-project 1.0.0 --host http://localhost:8000 --api-key +``` + #### Upload Project Icon To upload a icon, you don't need a token, except if you want to replace an existing icon. @@ -91,3 +116,9 @@ To set `example-image.png` as the icon for `awesome-project`, which already has ```sh curl -X POST -F "file=@example-image.png" --header "Docat-Api-Key: " http://localhost:8000/api/awesome-project/icon ``` + +Using `docatl`: + +```sh +docatl push-icon awesome-project example-image.png --host http://localhost:8000 --api-key +``` \ No newline at end of file From 88689be09ada4caefe2ef10daad1fa8997bac550 Mon Sep 17 00:00:00 2001 From: reglim Date: Fri, 21 Oct 2022 15:23:51 +0200 Subject: [PATCH 2/2] Docs: Add documentation for show, hide and rename As well as their docatl commands. fixes: #312, #322 --- doc/getting-started.md | 49 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/doc/getting-started.md b/doc/getting-started.md index 8df7841db..232aa78c9 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -121,4 +121,53 @@ Using `docatl`: ```sh docatl push-icon awesome-project example-image.png --host http://localhost:8000 --api-key +``` + +#### Rename a Project + +To rename a Project, you need a token. + +To rename `awesome-project` to `new-awesome-project`: + +```sh +curl -X PUT --header "Docat-Api-Key: " http://localhost:8000/api/awesome-project/rename/new-awesome-project +``` + +Using `docatl`: + +```sh +docatl rename awesome-project new-awesome-project --host http://localhost:8000 --api-key +``` + +#### Hide a Version + +If you want to hide a version from the version select as well as the search results, +you can hide it. You need to be authenticated to do this. + +To hide version `0.0.1` of `awesome-project`: + +```sh +curl -X POST --header "Docat-Api-Key: " http://localhost:8000/api/awesome-project/0.0.1/hide +``` + +Using `docatl`: + +```sh +docatl hide awesome-project 0.0.1 --host http://localhost:8000 --api-key +``` + +#### Show a Version + +This is the reverse of `hide`, and also requires a token. + +To show version `0.0.1` of `awesome-project` again: + +```sh +curl -X POST --header "Docat-Api-Key: " http://localhost:8000/api/awesome-project/0.0.1/show +``` + +Using `docatl`: + +```sh +docatl show awesome-project 0.0.1 --host http://localhost:8000 --api-key ``` \ No newline at end of file