Skip to content

Commit

Permalink
Improve docs clarity and usability (#1857)
Browse files Browse the repository at this point in the history 
* upgrade Docusaurus to v3

* add search functionality

* revamp various guides and introduce new ones

* change font to DM Sans

* add configuration options table generator

* add FAQ page

* add API reference and request builder
  • Loading branch information
@LordGhostX
LordGhostX committed May 21, 2024
1 parent 3d16548 commit 315cfd7
Show file tree
Hide file tree
Showing 64 changed files with 10,694 additions and 4,890 deletions.
41 changes: 29 additions & 12 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,44 @@
# Website
# Juno Documentation

This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
The Juno Documentation can be accessed at <https://juno.nethermind.io/> and is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

### Installation
## Installation

```
$ npm install
```bash
npm install
```

### Local Development
## Local Development

```
$ npm run start
```bash
npm run start # Run 'node generate-config.js' in the root directory to generate the Juno configuration options table
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build
## Deployment

```bash
npm run build # Runs 'node generate-config.js' and then 'docusaurus build'
# The 'generate-config.js' script extracts Juno's configuration details and generates a table for the Configuring Juno guide
```
$ npm run build

This command generates static content into the `build` directory and can be served using any static contents hosting service. Deployment is handled using GitHub pages.

## Troubleshooting

Docusaurus depends heavily on caching to improve site performance. If you make changes that do not appear in the website, try clearing the cache by running:

```bash
npm run clear
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.
## Versioning

To generate a new version of the documentation, run the following command:

```bash
npm run docusaurus docs:version <VERSION NAME>
```

Deployment is handled using GitHub pages.
To view versions of the documentation that have not yet been released, visit `http://localhost:3000/next/`.
48 changes: 48 additions & 0 deletions docs/docs/_config-options.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<!-- This file is generated automatically. Any manual modifications will be overwritten. -->

| Config Option | Default Value | Description |
| - | - | - |
| `cn-core-contract-address` | | Custom network core contract address |
| `cn-feeder-url` | | Custom network feeder URL |
| `cn-gateway-url` | | Custom network gateway URL |
| `cn-l1-chain-id` | | Custom network L1 chain id |
| `cn-l2-chain-id` | | Custom network L2 chain id |
| `cn-name` | | Custom network name |
| `cn-unverifiable-range` | `[]` | Custom network range of blocks to skip hash verifications (e.g. `0,100`) |
| `colour` | `true` | Use `--colour=false` command to disable colourized outputs (ANSI Escape Codes) |
| `config` | | The YAML configuration file |
| `db-cache-size` | `8` | Determines the amount of memory (in megabytes) allocated for caching data in the database |
| `db-max-handles` | `1024` | A soft limit on the number of open files that can be used by the DB |
| `db-path` | `juno` | Location of the database files |
| `eth-node` | | WebSocket endpoint of the Ethereum node. To verify the correctness of the L2 chain, Juno must connect to an Ethereum node and parse events in the Starknet contract |
| `grpc` | `false` | Enable the HTTP gRPC server on the default port |
| `grpc-host` | `localhost` | The interface on which the gRPC server will listen for requests |
| `grpc-port` | `6064` | The port on which the gRPC server will listen for requests |
| `gw-api-key` | | API key for gateway endpoints to avoid throttling |
| `gw-timeout` | `5` | Timeout for requests made to the gateway |
| `http` | `false` | Enables the HTTP RPC server on the default port and interface |
| `http-host` | `localhost` | The interface on which the HTTP RPC server will listen for requests |
| `http-port` | `6060` | The port on which the HTTP server will listen for requests |
| `log-level` | `info` | Options: trace, debug, info, warn, error |
| `max-vm-queue` | | Maximum number for requests to queue after reaching max-vms before starting to reject incoming requests. Default is set to double the value of `max-vms` |
| `max-vms` | | Maximum number for VM instances to be used for RPC calls concurrently. Default is set to three times the number of CPU cores |
| `metrics` | `false` | Enables the Prometheus metrics endpoint on the default port |
| `metrics-host` | `localhost` | The interface on which the Prometheus endpoint will listen for requests |
| `metrics-port` | `9090` | The port on which the Prometheus endpoint will listen for requests |
| `network` | `mainnet` | Options: mainnet, sepolia, sepolia-integration |
| `p2p` | `false` | EXPERIMENTAL: Enables p2p server |
| `p2p-addr` | | EXPERIMENTAL: Specify p2p source address as multiaddr |
| `p2p-feeder-node` | `false` | EXPERIMENTAL: Run juno as a feeder node which will only sync from feeder gateway and gossip the new blocks to the network |
| `p2p-peers` | | EXPERIMENTAL: Specify list of p2p peers split by a comma. These peers can be either Feeder or regular nodes |
| `p2p-private-key` | | EXPERIMENTAL: Hexadecimal representation of a private key on the Ed25519 elliptic curve |
| `pending-poll-interval` | `5` | Sets how frequently pending block will be updated (0s will disable fetching of pending block) |
| `pprof` | `false` | Enables the pprof endpoint on the default port |
| `pprof-host` | `localhost` | The interface on which the pprof HTTP server will listen for requests |
| `pprof-port` | `6062` | The port on which the pprof HTTP server will listen for requests |
| `remote-db` | | gRPC URL of a remote Juno node |
| `rpc-call-max-steps` | `4000000` | Maximum number of steps to be executed in starknet_call requests |
| `rpc-cors-enable` | `false` | Enable CORS on RPC endpoints |
| `rpc-max-block-scan` | `18446744073709551615` | Maximum number of blocks scanned in single starknet_getEvents call |
| `ws` | `false` | Enables the WebSocket RPC server on the default port |
| `ws-host` | `localhost` | The interface on which the WebSocket RPC server will listen for requests |
| `ws-port` | `6061` | The port on which the WebSocket server will listen for requests |
102 changes: 102 additions & 0 deletions docs/docs/configuring.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
title: Configuring Juno
---

# Configuring Juno :gear:

Juno can be configured using several methods, with the following order of precedence:

1. [Command line parameters (flags)](#command-line-params)
2. [Environment variables](#environment-variables)
3. [Configuration file](#configuration-file)

## Command line params

Juno can be configured directly on the command line by prefixing `--` to each option name:

```bash
./build/juno --http --http-port 6060 --http-host 0.0.0.0
```

When using Docker, append the command line parameters after the image name to configure Juno:

```bash
docker run nethermind/juno --http --http-port 6060 --http-host 0.0.0.0
```

:::tip
Command line parameters override [environment variables](#environment-variables) and [configuration file](#configuration-file).
:::

## Environment variables

Juno can be configured through environment variables by prefixing the variable names with `JUNO_` and using the configuration options in [SCREAMING_SNAKE_CASE](https://en.wiktionary.org/wiki/screaming_snake_case) format.

To set the `http`, `http-port`, and `http-host` configurations, Juno should be run in this format:

```bash
JUNO_HTTP=true JUNO_HTTP_PORT=6060 JUNO_HTTP_HOST=0.0.0.0 ./build/juno
```

When using Docker, start Juno using the `-e` command option:

```bash
docker run \
-e "JUNO_HTTP=true JUNO_HTTP_PORT=6060 JUNO_HTTP_HOST=0.0.0.0" \
nethermind/juno
```

:::tip
Environment variables rank second in configuration precedence. [Command line parameters](#command-line-params) override environment variables.
:::

## Configuration file

Juno can be configured using a [YAML](https://en.wikipedia.org/wiki/YAML) file:

```yaml title="Sample YAML File" showLineNumbers
log-level: info
network: mainnet
http: true
http-port: 6060
metrics: true
metrics-port: 9090
```

To run Juno with a configuration file, use the `config` option to specify the path of the configuration file:

```bash
# Standalone binary
./build/juno --config <CONFIG FILE PATH>

# Docker container
docker run nethermind/juno --config <CONFIG FILE PATH>
```

:::info
By default, Juno looks for the configuration file in the `$XDG_CONFIG_HOME` directory.
:::

:::tip
Configuration file rank third in configuration precedence. [Command line parameters](#command-line-params) and [environment variables](#environment-variables) override configuration file.
:::

## Configuration options

To list all available command line options, you can use the `--help` parameter:

```bash
# Standalone binary
./build/juno --help

# Docker container
docker run nethermind/juno --help
```

Below is a list of all configuration options available in Juno, along with their default values and descriptions:

```mdx-code-block
import ConfigOptions from "./_config-options.md";
<ConfigOptions />
```
64 changes: 0 additions & 64 deletions docs/docs/example_config.md
View file

This file was deleted.

Loading

0 comments on commit 315cfd7

Please sign in to comment.