From 69e43e40ebf23a0ec38c7117dddae4e072ff35c2 Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Wed, 2 Oct 2019 11:41:35 +0200 Subject: [PATCH] improving documentation --- .github/CODE_OF_CONDUCT.md | 2 +- .github/CONTRIBUTING.md | 4 ++-- .github/ISSUE_TEMPLATE.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 2 +- build/docs/content/12-scalability.md | 17 ++++++++--------- build/docs/content/13-ping.md | 2 +- build/docs/content/15-links.md | 1 + docs/index.html | 20 ++++++++++---------- 8 files changed, 25 insertions(+), 25 deletions(-) diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 42204861..1165dd4e 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -43,4 +43,4 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] [homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ffa62154..5fa0d548 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -8,7 +8,7 @@ find below useful information about how to contribute to the Gotenberg project. ### Install from sources 1. Install and run the latest version of Docker -2. Verify your Go version (>= 1.12) +2. Verify your Go version (>= 1.13) 3. Fork this repository 4. Clone it outside of your `GOPATH` (we're using Go modules) @@ -36,4 +36,4 @@ add a new one! * [Code of conduct](CODE_OF_CONDUCT.md) * [Issue template](ISSUE_TEMPLATE.md) -* [Pull request template](PULL_REQUEST_TEMPLATE.md) \ No newline at end of file +* [Pull request template](PULL_REQUEST_TEMPLATE.md) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index e1be6a09..fe595d44 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -32,4 +32,4 @@ Please search on the [issue tracker](../../../issues) before creating one. * Version used: * Operating System and version: -* Link to your project: \ No newline at end of file +* Link to your project: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ccc07b30..b758496e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -42,4 +42,4 @@ Fixes # - [ ] Have you successfully ran tests with your changes locally (`make tests`)? - [ ] Have you updated the documentation (`make doc`)? - [ ] I have squashed any insignificant commits -- [ ] This change has comments for package types, values, functions, and non-obvious lines of code \ No newline at end of file +- [ ] This change has comments for package types, values, functions, and non-obvious lines of code diff --git a/build/docs/content/12-scalability.md b/build/docs/content/12-scalability.md index 4424670b..924012b4 100644 --- a/build/docs/content/12-scalability.md +++ b/build/docs/content/12-scalability.md @@ -2,17 +2,18 @@ title: Scalability --- -Google Chrome and unoconv (LibreOffice) are intricate programs. +The API uses under the hood intricate programs. Gotenberg tries to abstract as much complexity as possible but it can only do it to a certain extend. -For instance, Google Chrome misbehaves if there are too many concurrent conversions. -That's why for [HTML](#html), [URL](#url) and [Markdown](#markdown) conversions, the API does only 6 conversions in parallel. -The more concurrent requests, the more `504` HTTP codes the API will return. +For instance, [Office](#office) and [Merge](#merge) endpoints will start respectively as many LibreOffice (unoconv) and PDTk +instances are there are requests. The limitation here is the available memory and CPU usage. -On another hand, for [Office](#office) conversions, the API will start as many unoconv (LibreOffice) instances as there are -requests. The limitation here is the available memory. +On another hand, for the [HTML](#html), [URL](#url) and [Markdown](#markdown) endpoints, the API does only 6 conversions in parallel. +Indeed, Google Chrome misbehaves if there are too many concurrent conversions. + +**The more concurrent requests, the more `504` HTTP codes the API will return.** > See our [load testing use case](../loadtesting) for more details about the API behaviour under heavy load. @@ -20,10 +21,8 @@ requests. The limitation here is the available memory. ### Increase timeout -This strategy is mostly for [HTML](#html), [URL](#url) and [Markdown](#markdown) conversions. - You may increase the conversion timeout. In other words, you accept that a conversion takes more time -if there are more than 6 conversions in parallel. +if the API is under heavy load. > See [timeout section](#timeout). diff --git a/build/docs/content/13-ping.md b/build/docs/content/13-ping.md index 3d661698..1535b607 100644 --- a/build/docs/content/13-ping.md +++ b/build/docs/content/13-ping.md @@ -8,5 +8,5 @@ a simple `GET` request. Currently this endpoint does nothing special. A better way to monitor Gotenberg would be by checking the memory usage. -Also, as Google Chrome and unoconv (LibreOffice) are intricate programs, you should +Also, as the API uses under the hood intricate programs, you should restart your Gotenberg instances from time to time to ensure a nominal behaviour. diff --git a/build/docs/content/15-links.md b/build/docs/content/15-links.md index 4c778b6f..23ac7d55 100644 --- a/build/docs/content/15-links.md +++ b/build/docs/content/15-links.md @@ -4,5 +4,6 @@ title: Links * Follow the progress on the [GitHub repository](https://github.com/thecodingmachine/gotenberg) * Follow [@gulnap](https://twitter.com/gulnap) on Twitter +* Thanks to [@mafredri](https://github.com/mafredri) for its help and its wonderful [cdp](https://github.com/mafredri/cdp) library Psst: TheCodingMachine is always looking for [talented coders](https://coders.thecodingmachine.com). diff --git a/docs/index.html b/docs/index.html index 0595a6e9..611db81c 100755 --- a/docs/index.html +++ b/docs/index.html @@ -1314,17 +1314,18 @@ $resp = $client->post($request);

Scalability

-

Google Chrome and unoconv (LibreOffice) are intricate programs.

+

The API uses under the hood intricate programs.

Gotenberg tries to abstract as much complexity as possible but it can only do it to a certain extend.

-

For instance, Google Chrome misbehaves if there are too many concurrent conversions. -That’s why for HTML, URL and Markdown conversions, the API does only 6 conversions in parallel. -The more concurrent requests, the more 504 HTTP codes the API will return.

+

For instance, Office and Merge endpoints will start respectively as many LibreOffice (unoconv) and PDTk +instances are there are requests. The limitation here is the available memory and CPU usage.

-

On another hand, for Office conversions, the API will start as many unoconv (LibreOffice) instances as there are -requests. The limitation here is the available memory.

+

On another hand, for the HTML, URL and Markdown endpoints, the API does only 6 conversions in parallel. +Indeed, Google Chrome misbehaves if there are too many concurrent conversions.

+ +

The more concurrent requests, the more 504 HTTP codes the API will return.

See our load testing use case for more details about the API behaviour under heavy load.

@@ -1338,10 +1339,8 @@ requests. The limitation here is the available memory.

Increase timeout -

This strategy is mostly for HTML, URL and Markdown conversions.

-

You may increase the conversion timeout. In other words, you accept that a conversion takes more time -if there are more than 6 conversions in parallel.

+if the API is under heavy load.

See timeout section.

@@ -1385,7 +1384,7 @@ a simple GET request.

Currently this endpoint does nothing special. A better way to monitor Gotenberg would be by checking the memory usage.

-

Also, as Google Chrome and unoconv (LibreOffice) are intricate programs, you should +

Also, as the API uses under the hood intricate programs, you should restart your Gotenberg instances from time to time to ensure a nominal behaviour.

@@ -1412,6 +1411,7 @@ restart your Gotenberg instances from time to time to ensure a nominal behaviour

Psst: TheCodingMachine is always looking for talented coders.