Skip to content

Commit

Permalink
[Documentation] Refactor poktroll documentation so its easier to navi…
Browse files Browse the repository at this point in the history
…gate (#474)

- No changes to the actual documentation
- Create navigation bar tabs
- Format the sidebar styling
- Auto-expand all sidebars
- Add search functionality (added after video was recorded)

**Before:**

https://github.com/pokt-network/poktroll/assets/1892194/b6bcc4fa-6504-432f-90ea-ab36f7bd4fdc

**After:**

https://github.com/pokt-network/poktroll/assets/1892194/5635ca1d-9f8d-48c5-906b-574c95c11b26
  • Loading branch information
Olshansk authored Apr 11, 2024
1 parent 195ad4b commit 279a573
Show file tree
Hide file tree
Showing 64 changed files with 1,879 additions and 1,276 deletions.
1 change: 1 addition & 0 deletions docusaurus/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,4 @@ GIT_USER=<Your GitHub username> yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

6 changes: 3 additions & 3 deletions docusaurus/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,14 @@ to build a better understanding of Pocket Network:

## Roadmap

You can details related to our roadmap [here](./roadmap/roadmap.md) and the
roadmap changelog [here](./roadmap/roadmap_changelog.md).
You can details related to our roadmap [here](./planning/roadmap/roadmap.md) and the
roadmap changelog [here](./planning/roadmap/roadmap_changelog.md).

## Getting Started

### Quickstart

The best way to get involved is by following the instructions [here](./developer_guide/quickstart.md).
The best way to get involved is by following the instructions [here](./develop/developer_guide/quickstart.md).

### Godoc

Expand Down
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ sidebar_position: 3
- [What is AppGate Server?](#what-is-appgate-server)
- [Architecture Overview](#architecture-overview)
- [Starting the AppGate Server](#starting-the-appgate-server)
- [Application Mode (self\_signing = true)](#application-mode-self_signing--true)
- [Application Mode (self_signing = true)](#application-mode-self_signing--true)
- [Application RPC Request Schema](#application-rpc-request-schema)
- [Gateway Mode (self\_signing = false)](#gateway-mode-self_signing--false)
- [Gateway Mode (self_signing = false)](#gateway-mode-self_signing--false)
- [Gateway RPC Request Schema](#gateway-rpc-request-schema)
- [POKTRollSDK integration](#poktrollsdk-integration)

Expand All @@ -20,7 +20,7 @@ sidebar_position: 3
`Gateway`s to relay RPC requests to the Pocket Network `Supplier`s without having
to manage the underlying logic of the protocol.

An operator only needs to specify a single [configuration file](configs/appgate_server_config.md),
An operator only needs to specify a single [configuration file](../../operate/configs/appgate_server_config.md),
in order to run a sovereign `Application` or a `Gateway` via an `AppGate Server`.

## Architecture Overview
Expand Down Expand Up @@ -62,7 +62,7 @@ poktrolld appgate-server \
--keyring-backend <keyring-type>
```

Where `<config-file>` is the path to the `.yaml` [appgate server config file](configs/appgate_server_config.md)
Where `<config-file>` is the path to the `.yaml` [appgate server config file](../../operate/configs/appgate_server_config.md)
and `<keyring-type>` is the backend to use for the keying. See the [cosmos documentation](https://docs.cosmos.network/v0.46/run-node/keyring.html)
for the full available set.

Expand All @@ -82,9 +82,9 @@ It takes care of things such as:

## Application Mode (self_signing = true)

If the [`self_signing`](configs/appgate_server_config.md#self_signing) field is
If the [`self_signing`](../../operate/configs/appgate_server_config.md#self_signing) field is
set to `true`, the `AppGate Server` will act as an `Application`. It will
only serve the address derived from the [`signing_key`](configs/appgate_server_config.md#signing_key).
only serve the address derived from the [`signing_key`](../../operate/configs/appgate_server_config.md#signing_key).

`RelayRequests` sent to the `AppGate Server` will be signed with the `signing_key`
resulting in a ring-signature that is only associated with the `Application`'s address.
Expand All @@ -102,7 +102,7 @@ When acting as an `Application`, the `AppGate Server` expects:

- The `serviceId` to be part of the URL path
- The payload to be the body of the POST request
- The request should be sent to the [`listening_endpoint`](configs/appgate_server_config.md#listening_endpoint) specified in the config file
- The request should be sent to the [`listening_endpoint`](../../operate/configs/appgate_server_config.md#listening_endpoint) specified in the config file

The following `curl` command demonstrates how to send a JSON-RPC type request
to the `AppGate Server`:
Expand All @@ -121,10 +121,10 @@ curl -X POST \

## Gateway Mode (self_signing = false)

If the [`self_signing`](configs/appgate_server_config.md#self_signing) field
If the [`self_signing`](../../operate/configs/appgate_server_config.md#self_signing) field
is set to `false`, then the `AppGate Server` will act as a `Gateway`, serving
`Application`s that delegated to the `Gateway` address represented by the
[`signing_key`](configs/appgate_server_config.md#signing_key).
[`signing_key`](../../operate/configs/appgate_server_config.md#signing_key).

The `AppGate Server` will determine the `Application` address to use by extracting
it from the `senderAddr` query parameter and use it along with the `signing_key` to
Expand All @@ -145,7 +145,7 @@ When acting as an `Gateway`, the `AppGate Server` expects:
- The `serviceId` to be part of the URL path
- The `payload` to be the body of the POST request
- The `Application` address as a query parameter in the request URL
- The request should be sent to the [`listening_endpoint`](configs/appgate_server_config.md#listening_endpoint) specified in the config file
- The request should be sent to the [`listening_endpoint`](../../operate/configs/appgate_server_config.md#listening_endpoint) specified in the config file

The following `curl` command demonstrates how to send a JSON-RPC type request
to the `AppGate Server`:
Expand Down Expand Up @@ -190,4 +190,4 @@ While `POKTRollSDK` manages:
- Verifying the `Supplier`'s signature.

A sequence diagram demonstrating the interaction between the `AppGate Server` and
the `POKTRollSDK` can be found in the [POKTRollSDK documentation](./../packages/sdk.md).
the `POKTRollSDK` can be found in the [POKTRollSDK documentation](../packages/sdk.md).
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ sidebar_position: 2
- [Features](#features)
- [Usage (`EventsQueryClient`)](#usage-eventsqueryclient)
- [Basic Example](#basic-example)
- [Advanced Usage](#advanced-usage)
- [Advanced Usage - Query Client](#advanced-usage---query-client)
- [Configuration](#configuration)
- [Usage (`EventsReplayClient`)](#usage-eventsreplayclient)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage-1)
- [- Replay Client](#--replay-client)
- [Best Practices](#best-practices)
- [FAQ](#faq)
- [Why use `events` over directly using Gorilla WebSockets?](#why-use-events-over-directly-using-gorilla-websockets)
Expand Down Expand Up @@ -238,7 +238,7 @@ for eitherEvent := range observer.Ch() {
}
```

### Advanced Usage
### Advanced Usage - Query Client

```go
// Given some custom dialer & connection implementation, e.g.:
Expand Down Expand Up @@ -359,19 +359,18 @@ lastEventType = latestEventsObs.Last(ctx, 1)[0]
cancel()
```

### Advanced Usage
### - Replay Client

The `EventsReplayClient` can be lightly wrapped to define a custom client for
a respective type. Examples of these include the `client.BlockClient` and
`client.DelegationClient` interfaces which under-the-hood are wrappers for the
`EventsReplayClient`.

:::danger
TODO: Update links for BlockClient and DelegationClient when they are added to the documentation.
TODO(@bryanchriswhite): Update links for BlockClient and DelegationClient when they are added to the documentation.
:::

See: [BlockClient](#TODO) and
[DelegationClient](#TODO) for more detailed examples
See: **BlockClient** and **DelegationClient** for more detailed examples
on how to wrap and use the `EventsReplayClient` in a more advanced setting.

## Best Practices
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loading

0 comments on commit 279a573

Please sign in to comment.