diff --git a/docs/_static/css/harp.css b/docs/_static/css/harp.css new file mode 100644 index 00000000..56672586 --- /dev/null +++ b/docs/_static/css/harp.css @@ -0,0 +1,30 @@ +.jumbo-toc table { + border: 2px solid #334155; +} + +.jumbo-toc table td { + border: 2px solid #334155; + vertical-align: top; +} + +.jumbo-toc table td > p > a:first-child { + font-size: 1.2em; + font-weight: bold; +} + +.jumbo-toc table ul { + margin: 0; + padding: 0; + list-style-type: none; + font-size: 0.9em; + display: flex; + flex-direction: row; + flex-wrap: wrap; + justify-content: space-between; +} + +.jumbo-toc table ul li { + flex-grow: 1; + flex-basis: auto; + text-align: center; +} diff --git a/docs/apps/index.rst b/docs/apps/index.rst new file mode 100644 index 00000000..d3cc42c6 --- /dev/null +++ b/docs/apps/index.rst @@ -0,0 +1,9 @@ +Applications +============ + +.. toctree:: + :maxdepth: 1 + + dashboard/index + proxy/index + sqlalchemy_storage/index diff --git a/docs/conf.py b/docs/conf.py index 458d9fce..6a89b4a0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,6 +40,7 @@ html_theme = "furo" html_static_path = ["_static"] html_js_files = ["js/links-target-blank.js"] +html_css_files = ["css/harp.css"] html_baseurl = "https://msqd.github.io/harp/" html_sidebars = { diff --git a/docs/development/applications/application-protocol.rst b/docs/contribute/applications/application-protocol.rst similarity index 100% rename from docs/development/applications/application-protocol.rst rename to docs/contribute/applications/application-protocol.rst diff --git a/docs/development/applications/dependency-injection.rst b/docs/contribute/applications/dependency-injection.rst similarity index 100% rename from docs/development/applications/dependency-injection.rst rename to docs/contribute/applications/dependency-injection.rst diff --git a/docs/development/applications/event-dispatcher.rst b/docs/contribute/applications/event-dispatcher.rst similarity index 100% rename from docs/development/applications/event-dispatcher.rst rename to docs/contribute/applications/event-dispatcher.rst diff --git a/docs/development/applications/index.rst b/docs/contribute/applications/index.rst similarity index 100% rename from docs/development/applications/index.rst rename to docs/contribute/applications/index.rst diff --git a/docs/development/benchmarks.rst b/docs/contribute/benchmarks.rst similarity index 100% rename from docs/development/benchmarks.rst rename to docs/contribute/benchmarks.rst diff --git a/docs/development/changelogs/0.1.3.rst b/docs/contribute/changelogs/0.1.3.rst similarity index 100% rename from docs/development/changelogs/0.1.3.rst rename to docs/contribute/changelogs/0.1.3.rst diff --git a/docs/development/changelogs/0.2.0.rst b/docs/contribute/changelogs/0.2.0.rst similarity index 100% rename from docs/development/changelogs/0.2.0.rst rename to docs/contribute/changelogs/0.2.0.rst diff --git a/docs/development/changelogs/0.2.1.rst b/docs/contribute/changelogs/0.2.1.rst similarity index 100% rename from docs/development/changelogs/0.2.1.rst rename to docs/contribute/changelogs/0.2.1.rst diff --git a/docs/development/changelogs/0.2.2.rst b/docs/contribute/changelogs/0.2.2.rst similarity index 100% rename from docs/development/changelogs/0.2.2.rst rename to docs/contribute/changelogs/0.2.2.rst diff --git a/docs/development/changelogs/0.2.3.rst b/docs/contribute/changelogs/0.2.3.rst similarity index 100% rename from docs/development/changelogs/0.2.3.rst rename to docs/contribute/changelogs/0.2.3.rst diff --git a/docs/development/changelogs/0.3.0.rst b/docs/contribute/changelogs/0.3.0.rst similarity index 100% rename from docs/development/changelogs/0.3.0.rst rename to docs/contribute/changelogs/0.3.0.rst diff --git a/docs/development/changelogs/0.3.1.rst b/docs/contribute/changelogs/0.3.1.rst similarity index 100% rename from docs/development/changelogs/0.3.1.rst rename to docs/contribute/changelogs/0.3.1.rst diff --git a/docs/development/changelogs/0.3.2.rst b/docs/contribute/changelogs/0.3.2.rst similarity index 100% rename from docs/development/changelogs/0.3.2.rst rename to docs/contribute/changelogs/0.3.2.rst diff --git a/docs/development/changelogs/0.4.0.rst b/docs/contribute/changelogs/0.4.0.rst similarity index 100% rename from docs/development/changelogs/0.4.0.rst rename to docs/contribute/changelogs/0.4.0.rst diff --git a/docs/development/changelogs/benchmarks/0.2.2-postgresql.svg b/docs/contribute/changelogs/benchmarks/0.2.2-postgresql.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.2.2-postgresql.svg rename to docs/contribute/changelogs/benchmarks/0.2.2-postgresql.svg diff --git a/docs/development/changelogs/benchmarks/0.2.2-sqlite.svg b/docs/contribute/changelogs/benchmarks/0.2.2-sqlite.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.2.2-sqlite.svg rename to docs/contribute/changelogs/benchmarks/0.2.2-sqlite.svg diff --git a/docs/development/changelogs/benchmarks/0.2.3-postgresql.svg b/docs/contribute/changelogs/benchmarks/0.2.3-postgresql.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.2.3-postgresql.svg rename to docs/contribute/changelogs/benchmarks/0.2.3-postgresql.svg diff --git a/docs/development/changelogs/benchmarks/0.2.3-sqlite.svg b/docs/contribute/changelogs/benchmarks/0.2.3-sqlite.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.2.3-sqlite.svg rename to docs/contribute/changelogs/benchmarks/0.2.3-sqlite.svg diff --git a/docs/development/changelogs/benchmarks/0.3.0-postgresql.svg b/docs/contribute/changelogs/benchmarks/0.3.0-postgresql.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.3.0-postgresql.svg rename to docs/contribute/changelogs/benchmarks/0.3.0-postgresql.svg diff --git a/docs/development/changelogs/benchmarks/0.3.0-sqlite.svg b/docs/contribute/changelogs/benchmarks/0.3.0-sqlite.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.3.0-sqlite.svg rename to docs/contribute/changelogs/benchmarks/0.3.0-sqlite.svg diff --git a/docs/development/changelogs/benchmarks/0.3.2-postgresql.svg b/docs/contribute/changelogs/benchmarks/0.3.2-postgresql.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.3.2-postgresql.svg rename to docs/contribute/changelogs/benchmarks/0.3.2-postgresql.svg diff --git a/docs/development/changelogs/benchmarks/0.3.2-sqlite.svg b/docs/contribute/changelogs/benchmarks/0.3.2-sqlite.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.3.2-sqlite.svg rename to docs/contribute/changelogs/benchmarks/0.3.2-sqlite.svg diff --git a/docs/development/changelogs/benchmarks/0.4.0-postgresql.svg b/docs/contribute/changelogs/benchmarks/0.4.0-postgresql.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.4.0-postgresql.svg rename to docs/contribute/changelogs/benchmarks/0.4.0-postgresql.svg diff --git a/docs/development/changelogs/benchmarks/0.4.0-sqlite.svg b/docs/contribute/changelogs/benchmarks/0.4.0-sqlite.svg similarity index 100% rename from docs/development/changelogs/benchmarks/0.4.0-sqlite.svg rename to docs/contribute/changelogs/benchmarks/0.4.0-sqlite.svg diff --git a/docs/development/changelogs/containers.rst b/docs/contribute/changelogs/containers.rst similarity index 100% rename from docs/development/changelogs/containers.rst rename to docs/contribute/changelogs/containers.rst diff --git a/docs/development/changelogs/index.rst b/docs/contribute/changelogs/index.rst similarity index 100% rename from docs/development/changelogs/index.rst rename to docs/contribute/changelogs/index.rst diff --git a/docs/development/ideas.rst b/docs/contribute/ideas.rst similarity index 100% rename from docs/development/ideas.rst rename to docs/contribute/ideas.rst diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst new file mode 100644 index 00000000..d923b05e --- /dev/null +++ b/docs/contribute/index.rst @@ -0,0 +1,21 @@ +Contributor's Guide +=================== + +.. toctree:: + :maxdepth: 2 + + introduction + extending + applications/index + storage/index + ../apps/dashboard/development/index + +Releases, Changes and Roadmap +::::::::::::::::::::::::::::: + +.. toctree:: + :maxdepth: 2 + + changelogs/index + roadmap + ideas diff --git a/docs/contribute/introduction.rst b/docs/contribute/introduction.rst new file mode 100644 index 00000000..332dd077 --- /dev/null +++ b/docs/contribute/introduction.rst @@ -0,0 +1,6 @@ +Introduction +============ + +The Contributor's Guide is there both to help you contribute to harp, but also to help you extend harp with your own +features. As most of the core features are implemented using applications (harp's extensions), this is a very good +starting point to write your own, even if you do not plan to publish them. diff --git a/docs/development/roadmap.rst b/docs/contribute/roadmap.rst similarity index 100% rename from docs/development/roadmap.rst rename to docs/contribute/roadmap.rst diff --git a/docs/development/storage/images/storage-model.png b/docs/contribute/storage/images/storage-model.png similarity index 100% rename from docs/development/storage/images/storage-model.png rename to docs/contribute/storage/images/storage-model.png diff --git a/docs/development/storage/index.rst b/docs/contribute/storage/index.rst similarity index 100% rename from docs/development/storage/index.rst rename to docs/contribute/storage/index.rst diff --git a/docs/develop/customize.rst b/docs/develop/customize.rst new file mode 100644 index 00000000..f1aedc20 --- /dev/null +++ b/docs/develop/customize.rst @@ -0,0 +1,11 @@ +Customize +========= + +Most features can be customized using configuration options. + +In this section, we'll go through the programmatic configuration options. + +.. note:: + + You can read about the declarative configuration options in the + :doc:`Operator's Guide Configure ` section. diff --git a/docs/develop/extend.rst b/docs/develop/extend.rst new file mode 100644 index 00000000..9ae83bb2 --- /dev/null +++ b/docs/develop/extend.rst @@ -0,0 +1,8 @@ +Extend +====== + +Extending harp is as simple as writing an harp application (which is a standard python package with some additional +instrumentation) and loading it within your configuration. + +To wrtie your own applications, please refer to the +:doc:`Contributor's Guide Applications section `. diff --git a/docs/develop/index.rst b/docs/develop/index.rst new file mode 100644 index 00000000..ef5327aa --- /dev/null +++ b/docs/develop/index.rst @@ -0,0 +1,9 @@ +Developer's Guide +================= + +.. toctree:: + :maxdepth: 2 + + run + customize + extend diff --git a/docs/develop/run.rst b/docs/develop/run.rst new file mode 100644 index 00000000..419fffe3 --- /dev/null +++ b/docs/develop/run.rst @@ -0,0 +1,8 @@ +Run +=== + +.. note:: + + This document describes the options to run the application on your local machine. Although the topic is similar, if + you're looking for a guide on how to deploy the application to a server, please refer to the + :doc:`runtime section of the operator's guide <../operator/runtime>`. diff --git a/docs/development/dependencies.rst b/docs/development/dependencies.rst deleted file mode 100644 index b6d45a23..00000000 --- a/docs/development/dependencies.rst +++ /dev/null @@ -1,4 +0,0 @@ -https://multidict.aio-libs.org/en/stable/ -Whistle -Rodi -Config diff --git a/docs/development/index.rst b/docs/development/index.rst deleted file mode 100644 index f2150431..00000000 --- a/docs/development/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Development -=========== - -.. toctree:: - :maxdepth: 2 - - applications/index - storage/index - changelogs/index - roadmap - ideas - ../apps/dashboard/development/index diff --git a/docs/features/agregation-and-splitting.rst b/docs/features/agregation-and-splitting.rst deleted file mode 100644 index 33f7bfd7..00000000 --- a/docs/features/agregation-and-splitting.rst +++ /dev/null @@ -1,2 +0,0 @@ -Agregation and Splitting -======================== diff --git a/docs/features/alerting.rst b/docs/features/alerting.rst deleted file mode 100644 index 8548c0cd..00000000 --- a/docs/features/alerting.rst +++ /dev/null @@ -1,3 +0,0 @@ -Alerting -======== -.. TODO remove or elaborate about the overview, maybe rename in monitoring diff --git a/docs/features/basics.rst b/docs/features/basics.rst deleted file mode 100644 index d701a398..00000000 --- a/docs/features/basics.rst +++ /dev/null @@ -1,75 +0,0 @@ -Basics -====== - -The basic goal of HARP is to be a nearline proxy to remote HTTP APIs, to enhance observability and reliability while -lowering development and maintenance cost by offloading all usual needed features to the proxy (caching, auditing, -alerting, retrying...). - -You can read more about the core HTTP proxy features in the :doc:`http-proxy` section of the documentation. - -By default, it respects HTTP cache headers and will speed up your API calls without further configuration. Of course, -a lot of APIs are non-standard or behave strangely, and one goal of HARP is to give you a toolkit for fixing those. - -Most usually complex but must-have features can be configured using very few lines of code (most often one or less), -and you can extend the existing or write your own using Python or Cython (for incredible speed and efficience, if -it's a need). - -Getting started -::::::::::::::: - -You run it locally, and query the local server instead of the remote API. - -The easiest way to get started is to run it through docker: - -.. # TO DO update this with a working command for docker -.. code-block:: bash - - docker run -it --rm -p 4000:4000 -p 4080:4080 -e HARP_ENDPOINT_URL=https://httpbin.org makersquad/harp-proxy - -Then you can query the proxy and get the same result as the remote API: - -.. code-block:: bash - - curl http://localhost:4000/get - -Open http://localhost:4080/ in your favorite browser and have a look to the proxy dashboard. You can inspect all -transactions (http request-response pairs) that went through the proxy. - -At his point you can already get a lot of value out of HARP, but you can also configure it to do (much) more. - -Please note that this default configuration is suited for development and testing, but not for production. Read the -production guide to learn about recommended settings for a live environment. - -Configuration -::::::::::::: - -Most of basic HARP settings can be set using environment variables. For a more readable or advanced setup, you can -configure it using its python API and/or a configuration file (various formats available like JSON, YAML, TOML, INI, ...). - -Here is a simple example of a bootstrap script that will do the exact same thing as the docker command above: - -.. TODO This is outdated, I don't think it exists anymore. -.. code-block:: python - - from harp import ProxyFactory - - proxy = ProxyFactory() - proxy.add("https://httpbin.org", port=4000) - - if __name__ == "__main__": - proxy.run() - -To run it with docker, save it as `proxy.py` use the following command (from the directory where you saved the file): - -.. code-block:: bash - - docker run -p 4000:4000 -p 4080:4080 -v "$(pwd)"/proxy.py:/etc/harp/entrypoint.py nginx - -Other ways to run -::::::::::::::::: - -Docker Compose --------------- - -Local Python Interpreter ------------------------- diff --git a/docs/features/batching.rst b/docs/features/batching.rst deleted file mode 100644 index 89bde7a8..00000000 --- a/docs/features/batching.rst +++ /dev/null @@ -1,5 +0,0 @@ -Batching -======== - -.. todo:: - remove? diff --git a/docs/features/caching.rst b/docs/features/caching.rst deleted file mode 100644 index f1fdd62d..00000000 --- a/docs/features/caching.rst +++ /dev/null @@ -1,5 +0,0 @@ -Caching -======= -.. todo:: - remove or elaborate? -Gentle, Strict, Stale-While-Revalidate ... diff --git a/docs/features/circuit-breaker.rst b/docs/features/circuit-breaker.rst deleted file mode 100644 index 7ed71872..00000000 --- a/docs/features/circuit-breaker.rst +++ /dev/null @@ -1,2 +0,0 @@ -Circuit Breaker -=============== diff --git a/docs/features/configuration.rst b/docs/features/configuration.rst deleted file mode 100644 index debe9e72..00000000 --- a/docs/features/configuration.rst +++ /dev/null @@ -1,4 +0,0 @@ -Configuration -============= -.. todo:: - remove? diff --git a/docs/features/dashboard.rst b/docs/features/dashboard.rst deleted file mode 100644 index a053e4df..00000000 --- a/docs/features/dashboard.rst +++ /dev/null @@ -1,2 +0,0 @@ -Dashboard -========= diff --git a/docs/features/debugging.rst b/docs/features/debugging.rst deleted file mode 100644 index 35ca717f..00000000 --- a/docs/features/debugging.rst +++ /dev/null @@ -1,2 +0,0 @@ -Debugging -========= diff --git a/docs/features/http-proxy.rst b/docs/features/http-proxy.rst deleted file mode 100644 index 54335fb9..00000000 --- a/docs/features/http-proxy.rst +++ /dev/null @@ -1,19 +0,0 @@ -HTTP Proxy -========== - -The HTTP Proxy is the very core feature of Harp. It is intended to be used as a sidecar, a service that runs just next -to your application. We call it "nearline proxy", because the network roundtrip to your service must be minimal to -non-existent for the proxy to give the most value. - -.. figure:: ./images/http-proxy-schema.png - :alt: Basic HTTP proxy schema - - Basic HTTP proxy schema - -.. todo:: - - Redraw the schema to make explicit the fact that user is in fact the user's application, and that harp is running - nearline. - -Harp proxies all HTTP methods, including non-standard ones. Some methods have special behaviors, like `HEAD` (response -body is ignored). But except for very special cases, Harp does not make any assumption about the HTTP method used. diff --git a/docs/features/images/http-proxy-schema.png b/docs/features/images/http-proxy-schema.png deleted file mode 100644 index 44f12008..00000000 Binary files a/docs/features/images/http-proxy-schema.png and /dev/null differ diff --git a/docs/features/index.rst b/docs/features/index.rst deleted file mode 100644 index 78b5d0db..00000000 --- a/docs/features/index.rst +++ /dev/null @@ -1,55 +0,0 @@ -Features -======== - -Basic features -:::::::::::::: - -A few basic features are available and probably required everytime you're using Harp Proxy. -Start here. - -.. toctree:: - :maxdepth: 1 - - basics - http-proxy - configuration - dashboard - -Common features -::::::::::::::: - -You may need this quite often although it's pre-configured with reasonable and respectful defaults. - -.. toctree:: - :maxdepth: 1 - - alerting - caching - circuit-breaker - retrying - -Advanced features -::::::::::::::::: - -Although those features are not required, they are quite useful in some cases. - -.. toctree:: - :maxdepth: 1 - - agregation-and-splitting - batching - intelligence - normalization-and-typing - prefetching - rewriting - routing - -Development features -:::::::::::::::::::: - -Some tools and candies for developers, to reduce time spent in development. - -.. toctree:: - :maxdepth: 1 - - debugging diff --git a/docs/features/intelligence.rst b/docs/features/intelligence.rst deleted file mode 100644 index 6262e6e5..00000000 --- a/docs/features/intelligence.rst +++ /dev/null @@ -1,4 +0,0 @@ -Intelligence -============ -.. todo:: - remove? diff --git a/docs/features/normalization-and-typing.rst b/docs/features/normalization-and-typing.rst deleted file mode 100644 index 00a0e19b..00000000 --- a/docs/features/normalization-and-typing.rst +++ /dev/null @@ -1,4 +0,0 @@ -Normalization and Typing -======================== -.. todo:: - remove? diff --git a/docs/features/prefetching.rst b/docs/features/prefetching.rst deleted file mode 100644 index 5c779e04..00000000 --- a/docs/features/prefetching.rst +++ /dev/null @@ -1,4 +0,0 @@ -Prefetching -=========== -.. todo:: - remove? diff --git a/docs/features/retrying.rst b/docs/features/retrying.rst deleted file mode 100644 index 84fde866..00000000 --- a/docs/features/retrying.rst +++ /dev/null @@ -1,4 +0,0 @@ -Retrying -======== -.. todo:: - remove? diff --git a/docs/features/rewriting.rst b/docs/features/rewriting.rst deleted file mode 100644 index 53534648..00000000 --- a/docs/features/rewriting.rst +++ /dev/null @@ -1,4 +0,0 @@ -Rewriting -========= -.. todo:: - remove? diff --git a/docs/features/routing.rst b/docs/features/routing.rst deleted file mode 100644 index 6e21e9a4..00000000 --- a/docs/features/routing.rst +++ /dev/null @@ -1,4 +0,0 @@ -Routing -======= -.. todo:: - remove? diff --git a/docs/index.rst b/docs/index.rst index e705ae6e..60a51da8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ Harp — HTTP API Runtime Proxy -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================= HARP operates as a sidecar proxy that sits between your application and remote APIs, elevating their reliability, performance, and security. By doing so, it also provides observability and reduces the amount of userland code required @@ -11,9 +11,9 @@ different purposes. .. figure:: images/tldr.png :alt: Basic proxy setup from the quickstart tl;dr -The core runtime of HARP primarily consists of two components: a proxy and a dashboard. The proxy is responsible for -forwarding requests to various endpoints, while the dashboard allows you to observe the requests passing through the -proxy. +The core runtime of HARP primarily consists of two components: a proxy (or a set of proxies) and a dashboard. Each proxy +is responsible for forwarding requests to its endpoint, while the dashboard allows you to observe the requests passing +through the proxies. HARP adopts a modular approach, where all features are implemented as independent and composable modules known as "applications." These applications can be enabled, disabled, extended, or arranged in different configurations to suit @@ -21,21 +21,50 @@ your specific requirements. While HARP provides sensible defaults to get you up limitless flexibility, allowing you to customize the proxy according to your unique needs. -Content -::::::: +.. table:: + :class: jumbo-toc + :widths: 50 50 + + +--------------------------------------------------------+--------------------------------------------------------+ + | :doc:`User's Guide ` | :doc:`Operator's Guide ` | + | | | + | Explore the user interface. | Install, configure and run the service. | + | | | + | - :doc:`/user/overview` | - :doc:`/operate/quickstart` | + | - :doc:`/user/transactions` | - :doc:`/operate/install/index` | + | - :doc:`/user/system` | - :doc:`/operate/configure/index` | + | - :doc:`/user/performances` | - :doc:`/operate/runtime` | + +--------------------------------------------------------+--------------------------------------------------------+ + | :doc:`Developer's Guide ` | :doc:`Contributor's Guide ` | + | | | + | Run, enhance and extend. | Dive in the internals. | + | | | + | - :doc:`/develop/run` | - :doc:`/contribute/introduction` | + | - :doc:`/develop/customize` | - :doc:`/contribute/applications/index` | + | - :doc:`/develop/extend` | - :doc:`/contribute/roadmap` | + +--------------------------------------------------------+--------------------------------------------------------+ + | :doc:`Reference ` | + | | + | - :doc:`Command Line Reference ` | + | - :doc:`Core API Reference ` | + | - :doc:`Applications Reference ` | + +--------------------------------------------------------+--------------------------------------------------------+ + + +Table of Content +:::::::::::::::: .. toctree:: :maxdepth: 2 - quickstart/index - features/index - installation/index - apps/index - commandline/index - configuration/index - reference/index - development/index - faq + /user/index + /operate/index + /develop/index + /contribute/index + /apps/index + /reference/index + /faq + Indices and tables :::::::::::::::::: diff --git a/docs/configuration/index.rst b/docs/operate/configure/index.rst similarity index 95% rename from docs/configuration/index.rst rename to docs/operate/configure/index.rst index ff1fc37a..57f9d3cb 100644 --- a/docs/configuration/index.rst +++ b/docs/operate/configure/index.rst @@ -1,5 +1,5 @@ -Configuration -============= +Configure +========= Configuration is built from different sources that may override each other. From lowest to hightest priority (lower items will override items configured by a higher item): diff --git a/docs/configuration/logging.rst b/docs/operate/configure/logging.rst similarity index 100% rename from docs/configuration/logging.rst rename to docs/operate/configure/logging.rst diff --git a/docs/configuration/storage.rst b/docs/operate/configure/storage.rst similarity index 100% rename from docs/configuration/storage.rst rename to docs/operate/configure/storage.rst diff --git a/docs/operate/index.rst b/docs/operate/index.rst new file mode 100644 index 00000000..92339890 --- /dev/null +++ b/docs/operate/index.rst @@ -0,0 +1,12 @@ +Operator's Guide +================ + +This guide is intended for operators that want to run HARP instances on live servers. + +.. toctree:: + :maxdepth: 2 + + quickstart + install/index + configure/index + runtime diff --git a/docs/installation/docker-compose.rst b/docs/operate/install/docker-compose.rst similarity index 100% rename from docs/installation/docker-compose.rst rename to docs/operate/install/docker-compose.rst diff --git a/docs/installation/docker.rst b/docs/operate/install/docker.rst similarity index 100% rename from docs/installation/docker.rst rename to docs/operate/install/docker.rst diff --git a/docs/installation/helm.rst b/docs/operate/install/helm.rst similarity index 100% rename from docs/installation/helm.rst rename to docs/operate/install/helm.rst diff --git a/docs/installation/index.rst b/docs/operate/install/index.rst similarity index 80% rename from docs/installation/index.rst rename to docs/operate/install/index.rst index a6aa53b0..23d55267 100644 --- a/docs/installation/index.rst +++ b/docs/operate/install/index.rst @@ -1,5 +1,5 @@ -Installation -============ +Install +======= The following diff --git a/docs/installation/pip.rst b/docs/operate/install/pip.rst similarity index 100% rename from docs/installation/pip.rst rename to docs/operate/install/pip.rst diff --git a/docs/installation/sources.rst b/docs/operate/install/sources.rst similarity index 100% rename from docs/installation/sources.rst rename to docs/operate/install/sources.rst diff --git a/docs/quickstart/index.rst b/docs/operate/quickstart.rst similarity index 78% rename from docs/quickstart/index.rst rename to docs/operate/quickstart.rst index baad6afd..5812d86a 100644 --- a/docs/quickstart/index.rst +++ b/docs/operate/quickstart.rst @@ -1,6 +1,18 @@ Quick start =========== +The main goal of HARP is to be a nearline proxy to remote HTTP APIs, to enhance observability and reliability while +lowering development, operations and maintenance costs. + +You can read more about the core HTTP proxy features in the :doc:`/features/http-proxy` section of the documentation. + +By default, it respects HTTP cache headers and will speed up your API calls without further configuration. Of course, +a lot of APIs are non-standard or behave strangely, and one goal of HARP is to give you a toolkit for fixing those. + +Most usually complex but must-have features can be configured using very few lines of code (most often one or less), +and you can extend the existing or write your own using Python or Cython (for incredible speed and efficience, if +it's a need). + Installation :::::::::::: diff --git a/docs/operate/runtime.rst b/docs/operate/runtime.rst new file mode 100644 index 00000000..175fddcf --- /dev/null +++ b/docs/operate/runtime.rst @@ -0,0 +1,7 @@ +Run +=== + +.. note:: + + This document describes the live deployment options. If you're looking for a guide on how to run harp locally, + please refer to the :doc:`run section of the developer's guide <../develop/run>`. diff --git a/docs/commandline/index.rst b/docs/reference/commandline/index.rst similarity index 100% rename from docs/commandline/index.rst rename to docs/reference/commandline/index.rst diff --git a/docs/reference/index.rst b/docs/reference/index.rst index b6ce302c..e17fa6fa 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -4,5 +4,6 @@ Reference .. toctree:: :maxdepth: 2 + commandline/index core/harp apps/harp_apps diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 00000000..c15a4f00 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,15 @@ +User's Guide +============ + +This guide intends to help dashboard users to understand the user interface elements and the metrics meaning. + +.. toctree:: + :maxdepth: 1 + + overview + transactions + system + performances + + +.. todo:: screenshots diff --git a/docs/user/overview.rst b/docs/user/overview.rst new file mode 100644 index 00000000..f51574e6 --- /dev/null +++ b/docs/user/overview.rst @@ -0,0 +1,10 @@ +Overview +======== + +The «Overview» tab shows agregated metrics about the system. + +Top metrics shows a quick summary over the last 24 hours, graphs shows agregated statistics for the the selected time +range. + + +.. todo:: screenshots diff --git a/docs/user/performances.rst b/docs/user/performances.rst new file mode 100644 index 00000000..e4f0f007 --- /dev/null +++ b/docs/user/performances.rst @@ -0,0 +1,4 @@ +Performances +============ + +.. todo:: graphs and formulas diff --git a/docs/user/system.rst b/docs/user/system.rst new file mode 100644 index 00000000..d2c0988f --- /dev/null +++ b/docs/user/system.rst @@ -0,0 +1,9 @@ +System +====== + +The «System» tab shows various informations about the currently running instance. It will help operators and developers +to understand how the running instance is configured. + +You probably don't need those informations unless you know what you are looking for. + +.. todo:: screenshots diff --git a/docs/user/transactions.rst b/docs/user/transactions.rst new file mode 100644 index 00000000..da786afb --- /dev/null +++ b/docs/user/transactions.rst @@ -0,0 +1,10 @@ +Transactions +============ + +The «Transactions» tab shows the list of all transactions that passed through the proxies. + +You can filter transactions using various criteria, and show the detailed content of each transactions. + +Transactions older than 3 months (default) are automaotically deleted, unless an user has marked them as favorite. + +.. todo:: screenshots