Merge pull request #1419 from input-output-hk/docs-restructure

Docs restructure

CHANGELOG.md

@@ -16,6 +16,10 @@ changes.
   from a script `UTxO`, and also unlock more involved use-cases, users need to provide additional
   unsigned transaction that correctly specifies required data (like redeemers, validity ranges etc.)
 
+- Update navigation and re-organized documentation website https://hydra.family
+  - Updated logos
+  - Removed localization as it got outdated and on-demand site translation tools exist.
+
 - Add `GET /snapshot/utxo` API endpoint to query confirmed UTxO set on demand.
   - Always responds with the last confirmed UTxO
 

demo/docker-compose.yaml

@@ -27,8 +27,6 @@ services:
     build:
       context: ../
       target: hydra-node
-    profiles:
-      - hydra-node
     volumes:
       - .:/keys:ro
       - ./devnet:/devnet
@@ -64,8 +62,6 @@ services:
     build:
       context: ../
       target: hydra-node
-    profiles:
-      - hydra-node
     volumes:
       - .:/keys:ro
       - ./devnet:/devnet
@@ -101,8 +97,6 @@ services:
     build:
       context: ../
       target: hydra-node
-    profiles:
-      - hydra-node
     volumes:
       - .:/keys:ro
       - ./devnet:/devnet
@@ -137,8 +131,6 @@ services:
     build:
        context: ../
        target: hydra-tui
-    profiles:
-      - tui
     command:
       [ "--connect", "172.16.238.10:4001"
       , "--node-socket", "/devnet/node.socket"
@@ -156,8 +148,6 @@ services:
     build:
        context: ../
        target: hydra-tui
-    profiles:
-      - tui
     command:
       [ "--connect", "172.16.238.20:4001"
       , "--node-socket", "/devnet/node.socket"
@@ -175,8 +165,6 @@ services:
     build:
        context: ../
        target: hydra-tui
-    profiles:
-      - tui
     command:
       [ "--connect", "172.16.238.30:4001"
       , "--node-socket", "/devnet/node.socket"

demo/run-docker.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 #
-# Prepare environment to run the demo cluster, then launches docker-compose demo.
-# If there's already a demo running, bail out.
+# Prepare environment to run the demo cluster, then launches docker compose
+# demo. If there's already a demo running, bail out.
 set -e
 
 SCRIPT_DIR=$(dirname $(realpath $0))
@@ -25,7 +25,7 @@ fi
 "${SCRIPT_DIR}/prepare-devnet.sh"
 ${DOCKER_COMPOSE_CMD} up -d cardano-node
 "${SCRIPT_DIR}/seed-devnet.sh"
-${DOCKER_COMPOSE_CMD} --profile hydra-node up -d
-echo >&2 -e "\n# Launch TUI on hydra-node-1: ${DOCKER_COMPOSE_CMD} --profile tui run hydra-tui-1"
+${DOCKER_COMPOSE_CMD} up -d hydra-node-{1,2,3}
+echo >&2 -e "\n# Launch TUI on hydra-node-1: ${DOCKER_COMPOSE_CMD} run hydra-tui-1"
 echo >&2 -e "\n# Stop the demo: ${DOCKER_COMPOSE_CMD} down\n"
-${DOCKER_COMPOSE_CMD} --profile tui run hydra-tui-1
+${DOCKER_COMPOSE_CMD} run hydra-tui-1

docs/README.md

@@ -42,31 +42,4 @@ nix build .#haddocks -o docs/static/haddock
 
 # Translating
 
-Translations of the documentation are provided in the `i18n/{lang}` folder (for example `i18n/fr` for French). Translations of both the content and the various website elements (such as buttons, headers etc...) are needed. To initialize a new language translation (e.g. `fr`), run the following command:
-
-```console
-$ yarn write-translations --locale fr
-```
-
-This command will pre-generate all the website elements which need to be translated into French (locale `fr`) in JSON files. Translations have to be provided for each items in generated JSON files, mapping ids to messages as such:
-
-```json
-{
-  "theme.TOCCollapsible.toggleButtonLabel": {
-    "message": "Sur cette page",
-    "description": "The label used by the button on the collapsible TOC component"
-  }
-}
-```
-
-> Note that only the value of the key `message` needs to be translated, the `description` simply provides context regarding the translated element and is automatically generated.
-
-In addition content files themselves (markdown) need to be copied under their respective directories, and then translated. Here is a table that summarizes the correspondence between the default website structure and their localized versions:
-
-| default          | translations                                                        |
-| ---------------- | ------------------------------------------------------------------- |
-| `docs/`          | `i18n/{lang}/docusaurus-plugin-content-docs/current/`               |
-| `benchmarks/`    | `i18n/{lang}/docusaurus-plugin-content-docs-benchmarks/current/`    |
-| `core-concepts/` | `i18n/{lang}/docusaurus-plugin-content-docs-core-concepts/current/` |
-| `topologies/`    | `i18n/{lang}/docusaurus-plugin-content-docs-topologies/current/`    |
-| `adr/`           | `i18n/{lang}/docusaurus-plugin-content-blog/current/`               |
+While we supported and encouraged contributing translations in the past, we turned off internationalization features as translations inevitably became out-of-date and on-demand translation of website became significantly better with AI language models. Nontheless, if you feel like we should offer translated pages and want to contribute that, please don't hesitate to file an [issue](https://github.com/input-output-hk/hydra/issues/new/choose).

docs/adr/2022-03-28_017-udp-networking.md

@@ -17,7 +17,7 @@ Current Hydra networking layer is based on [Ouroboros network framework](https:/
 2. A Multiplexing connection manager that manages a set of equivalent peers, maintains connectivity, and ensures diffusion of messages to/from all peers,
 2. Typed protocols for expressing the logic of message exchanges as a form of _state machine_.
 
-While it's been working mostly fine so far, the abstractions and facilities provided by this network layer are not well suited for Hydra Head networking. Some of the questions and shortcomings are discussed in a document on [Networking Requirements](/core-concepts/architecture/networking), and as the Hydra Head matures it seems time is ripe for overhauling current network implementation to better suite current and future Hydra Head networks needs.
+While it's been working mostly fine so far, the abstractions and facilities provided by this network layer are not well suited for Hydra Head networking. Some of the questions and shortcomings are discussed in a document on [Networking Requirements](/docs/dev/architecture/networking), and as the Hydra Head matures it seems time is ripe for overhauling current network implementation to better suite current and future Hydra Head networks needs.
 
 ## Decision
 

docs/core-concepts/behavior.md

@@ -4,6 +4,10 @@ sidebar_position: 4
 
 # API Behavior
 
+:::caution Deprecated
+This page will soon move into the [API reference](/api-reference) itself.
+:::
+
 This page documents the behavior of a `hydra-node` at the API layer. That is, how the system behaves given [ClientInputs](pathname:///haddock/hydra-node/Hydra-API-ClientInput.html#t:ClientInput) and what [ServerOutputs](pathname:///haddock/hydra-node/Hydra-API-ServerOutput.html#t:ServerOutput) are produced in response to it. See also the [API reference](/api-reference/) for more details about individual API messages. The only discrepancy is http `POST /commit` action which is not a state transition but a user action that submits a commit transaction which should produce `Committed` output.
 
 The formalism uses [UML statechart](https://en.wikipedia.org/wiki/UML_state_machine) language where transitions are labeled: `input [condition] / output`. When two outputs (e.g. `A` and `B`) are expected we write `A,B`, while `{A,B}` denotes mutual exclusiveness of outputs.

docs/core-concepts/index.md

@@ -2,24 +2,7 @@
 sidebar_position: 1
 ---
 
-# Overview
-
-Hydra is the layer 2 scalability solution for Cardano, which aims to increase transaction speed through low latency and high throughput and minimize transaction cost.
-
-[Hydra Head](https://eprint.iacr.org/2020/299.pdf) is the first protocol of the Hydra family and embodies the foundation for more advanced deployment scenarios relying on isomorphic, multi-party state-channels. For an introduction to the protocol also check out these two blog posts
-
- - [Hydra – Cardano’s solution for ultimate Layer 2 scalability](https://iohk.io/en/blog/posts/2021/09/17/hydra-cardano-s-solution-for-ultimate-scalability/)
- - [Implementing Hydra Heads: the first step towards the full Hydra vision ](https://iohk.io/en/blog/posts/2022/02/03/implementing-hydra-heads-the-first-step-towards-the-full-hydra-vision/)
-
-There are different flavors and extensions of the Hydra Head protocol, but let's start by looking at the full lifecycle of a basic Hydra Head, and how it allows for isomorphic state transfer between layer 1 and layer 2.
-
-![](./hydra-head-lifecycle.svg)
-
-A Hydra Head is formed by a group of online and responsive participants. Participants **init**ialize a Head by announcing several parameters on-chain, including the participants list. Then each of the participants **commit**s unspent transaction outputs (UTXOs) from the Cardano main-chain to it, before all the UTXOs are **collect**ed and made available in a Hydra Head as initial state (`U0`). At any moment before collecting, participants can also **abort** the process and recover their funds.
-
-While open, they can use the Hydra Head via a hydra-node to submit transactions over the Head network. Transactions have the same format and properties as on the main-chain: they are _isomorphic_. When UTXO entries are spent, and new UTXO entries are created in a Hydra Head, all participants are required to acknowledge and agree on the new state in so-called snapshots (`U1..Un`). Snapshots are _not_ posted back onto the layer 1, but are only kept around by the participants.
-
-Any participant can **close** the Head using a snapshot, when for example they wish to cash out on the mainnet, or if another party misbehaves or stalls the Head's evolution. There is a mechanism to **contest** the final state on the main chain. Ultimately, a **fanout** transaction distributes the final agreed state and makes available on the layer 1 what only existed virtually in the Head.
+# Core Concepts
 
 ```mdx-code-block
 import DocCardList from '@theme/DocCardList';