Explain environment variables in docs

packages/docs/components/Expandable.tsx

@@ -0,0 +1,19 @@
+import React, { useState, useEffect } from 'react';
+
+
+const Expandable= ({ children }) => {
+    const [expanded, setExpanded] = useState(false);
+
+    const toggleExpand = () => {
+        setExpanded(!expanded);
+    };
+
+    return (
+        <div>
+            {children}
+            <button onClick={toggleExpand}>{expanded ? 'Collapse' : 'Expand'}</button>
+        </div>
+    );
+};
+
+export default Expandable;

packages/docs/pages/_meta.json

@@ -1,8 +1,7 @@
 {
   "index": "Namada",
   "introduction": "Introduction",
-  "running-a-full-node": "Full nodes",
-  "ledger": "Running the ledger",
+  "ledger": "Full nodes",
   "validators": "Validators",
   "delegators": "Delegators",
   "users": "(Power) Users",

packages/docs/pages/introduction/testnets.mdx

@@ -19,7 +19,7 @@ If you find a bug, please submit an issue with the `bug` [issue template](https:
 3. [Pre-genesis validator setup](../../validators/genesis-validator-setup.md)
 4. [Pre-genesis validator apply](./testnets/genesis-validator-apply.md)
 5. [Running your genesis validator](../../validators/run-your-genesis-validator.md)
-6. [Running a full node](../../running-a-full-node.md)
+6. [Running a full node](../../ledger/running-a-full-node.md)
 7. [Becoming a validator post-genesis](./testnets/post-genesis-validator.md)
    ![testnet_flowchart](/images/testnet_flowchart.png)
 

packages/docs/pages/introduction/testnets/joining-the-testnet.mdx

@@ -8,7 +8,7 @@ Joining the testnet validator is identical to that of a mainnet validator.
 For this reason, please refer to [these docs](../../validators/run-your-genesis-validator.md).
 
 ## Joining as a full node
-If you are not a genesis validator, please follow the steps for [joining as a full node](../../running-a-full-node.md). 
+If you are not a genesis validator, please follow the steps for [joining as a full node](../../ledger/running-a-full-node.md). 
 
 It is then possible to test being a validator by [becoming a post-genesis validator](./post-genesis-validator.md).
 

packages/docs/pages/introduction/testnets/post-genesis-validator.mdx

@@ -2,7 +2,7 @@
 
 After genesis, you can still join the network as a user and become a validator through self-bonding. 
 
-After [joining the network as a full node](../../running-a-full-node.md), you must [create a validator account](../../validators/post-genesis-validator-setup.md).
+After [joining the network as a full node](../../ledger/running-a-full-node.md), you must [create a validator account](../../validators/post-genesis-validator-setup.md).
 
 After this has been completed, you will need to increase your validator's `bonded-stake`, which can be done by self-bonding tokens sourced from the faucet.
 

packages/docs/pages/introduction/testnets/pre-genesis.mdx

@@ -6,4 +6,4 @@ At genesis, there will be a set of validators with a pre-defined amount of token
 For testnets, it is possible to apply to become a pre-genesis validator.
 In order to do so, please follow [these steps](./genesis-validator-apply.md).
 
-If the testnet is already running and you have not been selected as a pre-genesis validator, please follow the steps for [joining as a full node](../../running-a-full-node.md). If you still wish to validate, you can follow the steps to [become a post-genesis-validator](./post-genesis-validator.md).
+If the testnet is already running and you have not been selected as a pre-genesis validator, please follow the steps for [joining as a full node](../../ledger/running-a-full-node.md). If you still wish to validate, you can follow the steps to [become a post-genesis-validator](./post-genesis-validator.md).

packages/docs/pages/introduction/testnets/upgrades.mdx

@@ -13,7 +13,7 @@ No upgrade needed on `public-testnet-9` (yet).
 The testnet launches on 20/06/2023 at 17:00 UTC with the genesis validators from `public-testnet-9`. It launches with [version v0.17.3](https://github.com/anoma/namada/releases/tag/v0.17.3) and chain-id `TBD`. 
 If your genesis transaction is contained in [this folder](https://github.com/anoma/namada-testnets/tree/main/namada-public-testnet-9), you are one of the genesis validators. In order for the testnet to come online, at least 2/3 of those validators need to be online.
 
-The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../running-a-full-node.md).
+The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../ledger/running-a-full-node.md).
 
 ## Previous upgrades:
 
@@ -32,7 +32,7 @@ The intended fix to solve the storage issue was only partially solved. This led
 The testnet launches on 29/03/2023 at 17:00 UTC with the genesis validators from `public-testnet-6`. It launches with [version v0.14.3](https://github.com/anoma/namada/releases/tag/v0.14.3) and chain-id `public-testnet-6.0.a0266444b06`. 
 If your genesis transaction is contained in [this folder](https://github.com/anoma/namada-testnets/tree/main/namada-public-testnet-5), you are one of the genesis validators. In order for the testnet to come online, at least 2/3 of those validators need to be online.
 
-The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../running-a-full-node.md).
+The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../ledger/running-a-full-node.md).
 
 ***13/02/2023*** `public-testnet-3`
 

packages/docs/pages/ledger.mdx

@@ -2,7 +2,9 @@ import { Callout } from 'nextra-theme-docs'
 
 # The Namada Ledger
 
-To start a local Namada ledger node, run:
+In order to make any interactions with the Namada blockchain through the Namada *client* `namadac`, the ledger must be running. 
+
+To start a local Namada ledger node, one can run:
 
 ```shell copy
 namada ledger
@@ -15,38 +17,27 @@ The node will attempt to connect to the persistent validator nodes and other pee
 
 By default, the ledger will store its configuration and state in your [base directory](./introduction/base-directory.md). 
 You can use the `--base-dir` CLI global argument or `BASE_DIR` environment variable to change it.
-</Callout>
 
 Assuming you do not have a custom base_dir, you can export the BASE_DIR environment variable as follows:
 
 ```shell copy
 export BASE_DIR=$(namadac utils default-base-dir)
 ```
+</Callout>
 
-The ledger also needs access to the built WASM files that are used in the genesis block. These files are included in release and shouldn't be modified, otherwise your node will fail with a consensus error on the genesis block. By default, these are expected to be in the `wasm` directory inside the chain directory that's in the base directory. This can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` environment variable or the configuration file.
+When the ledger is run for the first time, the MASP-parameters will be downloaded. This is essential for producing the zero knowledge proofs required to make shielded transactions.
 
-The ledger configuration is stored in `$BASE_DIR/{chain_id}/config.toml` (with
+### The ledger wasm files
+The ledger will also download the genesis block, which contains the initial state of the blockchain.
+The ledger also needs access to the built WASM files that are used in the genesis block. 
+These files are included in release and shouldn't be modified, otherwise your node will fail with a consensus error on the genesis block. 
+By default, these are expected to be in the `wasm` directory inside the chain directory that's in the base directory, i.e `$BASE_DIR/$CHAIN_ID/wasm`.
+The wasm directory can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` [environment variable](./ledger/env-vars.md) or the configuration file.
+
+### Ledger configuration
+The ledger configuration is stored in `$BASE_DIR/$CHAIN_ID/config.toml` (with
 default `--base-dir`). It is created when you join the network. You can modify
 that file to change the configuration of your node. All values can also be set
-via environment variables. 
+via [environment variables](./ledger/env-vars.md). 
 
-Names of the recognized environment variables are
-derived from the configuration keys by: uppercase every letter of the key,
-insert `.` or `__` for each nested value and prepend `NAMADA_`. For example,
-option `p2p_pex` in `[ledger.cometbft]` can be set by
-```shell copy
-NAMADA_LEDGER__COMETBFT__P2P_PEX=true # or false, depending on your heart's desires
-``` 
-or
-```shell copy
-NAMADA_LEDGER.COMETBFT.P2P_PEX=true # or false, depending on your heart's desires
-``` 
-in the environment 
-
-<Callout>
-**Note**: 
 
-Only the double underscore form can be 
-used in Bash, because Bash doesn't allow dots in
-environment variable names
-</Callout>

packages/docs/pages/ledger/_meta.json

@@ -0,0 +1,4 @@
+{
+    "env-vars": "Environment variables",
+    "running-a-full-node": "Running a full node"
+}

packages/docs/pages/ledger/env-vars.mdx

@@ -0,0 +1,66 @@
+import { Callout } from 'nextra-theme-docs'
+import Expandable from "../../components/Expandable"; // TODO: Use this component when properly css'd
+
+# Environment variables
+
+By default, whenever the namada ledger is started, it will apply the confirguration found in the ledger configuration file.
+
+An example of a ledger configuration file is displayed below.
+
+<Expandable>
+```toml
+wasm_dir = "wasm"
+
+[ledger]
+genesis_time = "2023-06-29T17:00:00+00:00"
+chain_id = "public-testnet-10.3718993c3648"
+
+[ledger.shell]
+base_dir = "/Users/fraccaman/Library/Application Support/Namada"
+storage_read_past_height_limit = 3600
+db_dir = "db"
+cometbft_dir = "cometbft"
+tendermint_mode = "Full"
+
+[ledger.cometbft]
+proxy_app = "tcp://127.0.0.1:26658"
+moniker = "technodrome"
+db_backend = "goleveldb"
+db_dir = "data"
+log_level = "info"
+log_format = "plain"
+genesis_file = "config/genesis.json"
+node_key_file = "config/node_key.json"
+abci = "socket"
+filter_peers = false
+priv_validator_key_file = "config/priv_validator_key.json"
+priv_validator_state_file = "data/priv_validator_state.json"
+priv_validator_laddr = ""
+
+...
+```
+</Expandable>
+
+However, it is possible to override the configuration by setting environment variables.
+Any variable found in the config can be accessed through environment variables that are constructed in the below manner.
+
+### Constructing environment variables
+Names of the recognized environment variables are derived from the configuration keys by:
+
+1. Prepend `NAMADA_` to the key
+2. Uppercase every letter of the key. For example `p2p_pex` becomes `P2P_PEX`
+3. Insert a `__` for each nested value. For example, `ledger.cometbft` becomes `LEDGER__COMETBFT`
+
+Hence, the option `p2p_pex` in `[ledger.cometbft]` can be set by
+```shell copy
+NAMADA_LEDGER__COMETBFT__P2P_PEX=true # or false, depending on your heart's desires
+``` 
+in the environment 
+
+<Callout type="warning">
+**Note**: 
+In principle, even `.` can be used for environment variable names. 
+However, in Bash, only the double underscore form can be 
+used, because Bash doesn't allow dots in environment variable names. 
+Therefore, we omit the dot form.
+</Callout>