docs: major overhaul (#19395)

_config.yml

@@ -29,32 +29,41 @@ collections:
     output: true
     caption: Install and build
     sidebar_index: 1
-  how-to:
-    output: true
-    caption: How to use
-    sidebar_index: 2
+    frontpage: _install-and-build/Installing-Geth.md
   interface:
-    output: true
-    caption: Interface documentation
-    sidebar_index: 3
+    output: true  
+    caption: Interacting with Geth
+    sidebar_index: 2
   support:
     output: true
     caption: Issues and support
-    sidebar_index: 4
+    sidebar_index: 3
   developers:
     output: true
-    caption: Developers
-    sidebar_index: 5
+    caption: Developer docs
+    sidebar_index: 4
   clef:
     output: true
     caption: Clef
-    sidebar_index: 6
+    sidebar_index: 5
+    frontpage: _clef/Overview.md
   whisper:
     output: true
     caption: Whisper
+    sidebar_index: 6
+    frontpage: _whisper/Whisper-Overview.md
+  swarm:
+    output: true
+    caption: Swarm
     sidebar_index: 7
   doc:
     output: true
     caption: Other
     sidebar_index: 8
+  legacy:
+    output: true
+    caption: Legacy content
+    sidebar_index: 9
+
+
 

_includes/head.html

@@ -7,28 +7,20 @@
     <!-- debug root:{% include link.html url="/debug-path" %} -->
 
     <link rel="icon" type="image/png" href="{% include link.html url=site.favicon %}" />
-    {% if layout.common-css %}
-        {% for css in layout.common-css %}
-    <link rel="stylesheet" href="{% include link.html url=css %}" />
-        {% endfor %}
-    {% endif %}
+{% for x in layout.common-css %}{% capture target %}{% include link.html url=x %}{% endcapture %}
+    <link rel="stylesheet" href="{{ target |strip }}" />
+{% endfor %}
 
-    {% if page.css %}
-        {% for css in page.css %}
-    <link rel="stylesheet" href="{% include link.html url=css %}" />
-        {% endfor %}
-    {% endif %}
+{% for x in page.css %}{% capture target %}{% include link.html url=x %}{% endcapture %}
+    <link rel="stylesheet" href="{{ target |strip }}" />
+{% endfor %}
 
-    {% if layout.common-js %}
-        {% for js in layout.common-js %}
-    <script src="{% include link.html url=js %}"></script>
-        {% endfor %}
-    {% endif %}
-  
-    {% if page.js %}
-        {% for js in page.js %}
-    <script src="{% include link.html url=js %}"></script>
-        {% endfor %}
-    {% endif %}
+{% for x in layout.common-js %}{% capture target %}{% include link.html url=x %}{% endcapture %}
+    <script src="{{ target | strip }}"></script>
+{% endfor %}
 
-</head>
+{% for x in page.js %}{% capture target %}{% include link.html url=x %}{% endcapture %}
+    <script src="{{ target | strip }}"></script>
+{% endfor %}
+  
+</head>

_includes/link.html

@@ -1,2 +1 @@
-{% capture root %}{% if page.root %}{{ page.root }}{% else %}{{ site.default_root }}{% endif %}{% endcapture %}
-{{ include.url | remove: ".html" | prepend: root | replace: '//', '/' }}
+{% if page.root %}{% assign root=page.root %}{% else %}{% assign root=site.default_root %}{% endif %}{{ include.url | remove: ".html" | prepend: root | replace: '//', '/' }}

_layouts/default.html

@@ -30,10 +30,9 @@ common-js:
         </div>
         <div id="navbar" class="navbar-collapse collapse">
           <ul class="nav navbar-nav">
-              {% for link in site.data.navbar %}
-              <li>
-                  <a href="{% include link.html url=link.last %}">{{ link.first }}</a>
-              </li>
+            {% for link in site.data.navbar %}
+	    {% capture target %}{% include link.html url=link.last %}{% endcapture %}
+              <li><a href="{{target |strip }}">{{ link.first }}</a></li>
               {% endfor %}
           </ul>
         </div>

_layouts/sidebar.html

@@ -1,37 +1,37 @@
 ---
 layout: default
 ---
+
+{% assign toplevels = site.collections| where_exp: "item", "item.sidebar_index" | sort:"sidebar_index" %}
 <div class="container" style="padding-top: 24px;">
-    <div class="row">
-          <div class="col-md-3" id="toc" style="padding-top: 16px;">
-            {% assign collections = site.collections | sort: "sidebar_index" %}
-            {% for coll in collections %}
-                {% if coll.sidebar_index %}
-                    {% assign count = coll.docs | size %}
-                    {% if count <= 8 %}
-                        <div class="list-group">
-                            <a class="list-group-item active">{{ coll.caption }}</a>
-                            {% for doc in coll.docs %}
-                                <a class="list-group-item" 
-                                    href="{% include link.html url=doc.url %}">
-                                    {% include title.html doc=doc coll=coll %}</a>
-                            {% endfor %}
-                        </div>
-                    {% else %}
-                        {% capture url %}/{{ coll.label }}{% endcapture %}
-                        <div class="list-group">
-                            <a class="list-group-item active"
-                               href="{% include link.html url=url %}">{{ coll.caption }}</a>
-                        </div>
-                    {% endif %}
-                {% endif %}
-            {% endfor %}
-          </div>
-          <div class="col-md-9" id="content">
-            {% if page.title %}
-            <h1 class="featurette-heading">{% include title.html doc=page coll=page.collection %}</h1>
-            {% endif %}
-            {{ content }}
-          </div>
+  <div class="row">
+    <div class="col-md-3" id="toc" style="padding-top: 16px;">      
+{% for group in toplevels %}
+    {% assign frontdoc=group.docs| where_exp: "doc","doc.path == group.frontpage"|first %}
+    {% unless frontdoc %}
+      {% assign frontdoc=group.docs[0] %}      
+    {% endunless  %}
+  {% capture target %}{% include link.html url=frontdoc.url %}{% endcapture %}
+    <div class="list-group">
+      <a class="list-group-item active" href="{{ target |strip }}">{{ group.caption }}</a>
+  {% if page.collection == group.label  %}
+    {% for doc in group.docs %}
+      {% assign classmodifier="" %}
+      {% if doc.url == page.url %}
+        {% assign classmodifier="disabled" %}
+	{% endif %}
+	{% capture target %}{% include link.html url=doc.url %}{% endcapture %}
+        <a class="list-group-item {{classmodifier}}" href="{{ target |strip }}">{% include title.html doc=doc coll=group %}</a>
+    {% endfor %}
+  {% endif %}
+      </div>
+{% endfor %}
     </div>
-</div>
+    <div class="col-md-9" id="content">
+{% if page.title %}
+  <h1 class="featurette-heading">{% include title.html doc=page coll=page.collection %}</h1>
+{% endif %}
+  {{ content }}
+    </div>
+  </div>
+</div>

docs/_developers/Developer-Guide.md

@@ -13,12 +13,3 @@ title: Developer guide
 
 [Account management](Mobile:-Account-management)
 
-### Transaction tracing
-
-[Introduction and basics](Tracing:-Introduction)
-
-[Custom in-node tracers](Tracing:-Custom-tracers)
-
-[Full blockchain tracing](Tracing:-Blockchain-tracing)
-
-[Dependency exfiltration](Tracing:-Exfiltration)

docs/_doc/Gas-Price-Oracle.md

@@ -3,20 +3,20 @@ title: Gas price oracle
 ---
 The gas price oracle is a helper function of the Geth client that tries to find an appropriate default gas price when sending transactions. It can be parametrized with the following command line options:
 
-- gpomin: lower limit of suggested gas price. This should be set at least as high as the "gasprice" setting usually used by miners so that your transactions will not be rejected automatically because of a too low price.
+- `gpomin`: lower limit of suggested gas price. This should be set at least as high as the `gasprice` setting usually used by miners so that your transactions will not be rejected automatically because of a too low price.
 
-- gpomax: higher limit of suggested gas price. During load peaks when there is a competition between transactions to get into the blocks, the price needs to be limited, otherwise the oracle would eventually try to overbid everyone else at any price.
+- `gpomax`: higher limit of suggested gas price. During load peaks when there is a competition between transactions to get into the blocks, the price needs to be limited, otherwise the oracle would eventually try to overbid everyone else at any price.
 
-- gpofull: a block is considered "full" when a certain percentage of the block gas limit (specified in percents) is used up by transactions. If a block is not "full", that means that a transaction could have been accepted even with a minimal price offered.
+- `gpofull`: a block is considered "full" when a certain percentage of the block gas limit (specified in percents) is used up by transactions. If a block is not "full", that means that a transaction could have been accepted even with a minimal price offered.
 
-- gpobasedown: an exponential ratio (specified in 1/1000ths) by which the base price decreases when the lowest acceptable price of the last block is below the last base price.
+- `gpobasedown`: an exponential ratio (specified in `1/1000ths`) by which the base price decreases when the lowest acceptable price of the last block is below the last base price.
 
-- gpobaseup: an exponential ratio (specified in 1/1000ths) by which the base price increases when the lowest acceptable price of the last block is over the last base price.
+- `gpobaseup`: an exponential ratio (specified in `1/1000ths`) by which the base price increases when the lowest acceptable price of the last block is over the last base price.
 
-- gpobasecf: a correction factor (specified in percents) of the base price. The suggested price is the corrected base price, limited by gpomin and gpomax.
+- `gpobasecf`: a correction factor (specified in percents) of the base price. The suggested price is the corrected base price, limited by `gpomin` and `gpomax`.
 
 The lowest acceptable price is defined as a price that could have been enough to insert a transaction into a certain block. Although this value varies slightly with the gas used by the particular transaction, it is aproximated as follows: if the block is full, it is the lowest transaction gas price found in that block. If the block is not full, it equals to gpomin.
 
 The base price is a moving value that is adjusted from block to block, up if it was lower than the lowest acceptable price, down otherwise. Note that there is a slight amount of randomness added to the correction factors so that your client will not behave absolutely predictable on the market.
 
-If you want to specify a constant for the default gas price and not use the oracle, set both gpomin and gpomax to the same value.
+If you want to specify a constant for the default gas price and not use the oracle, set both `gpomin` and `gpomax` to the same value.

docs/_doc/Installation-Instructions-for-Ubuntu.md

@@ -1,48 +0,0 @@
----
-title: Installation instructions for Ubuntu
----
-## Installing from PPA
-
-```shell
-sudo apt-get install software-properties-common
-sudo add-apt-repository -y ppa:ethereum/ethereum
-sudo apt-get update
-sudo apt-get install ethereum
-```
-
-If you want to stay on the bleeding edge, install the `ethereum-unstable` package instead.
-
-After installing, run `geth account new` to create an account on your node.
-
-You should now be able to run `geth` and connect to the network.
-
-Make sure to check the different options and commands with `geth --help`
-
-You can alternatively install only the `geth` CLI with `apt-get install geth` if you don't want to install the other utilities (`bootnode`, `evm`, `disasm`, `rlpdump`, `ethtest`).
-
-## Building from source
-
-### Building Geth (command line client)
-
-Clone the repository to a directory of your choosing:
-
-```shell
-git clone https://github.com/ethereum/go-ethereum
-```
-Install latest distribution of Go (v1.12.1) if you don't have it already:
-
-[See instructions](Installing-Go#ubuntu-1404)
-
-Building `geth` requires Go and C compilers to be installed:
-
-```shell
-sudo apt-get install -y build-essential golang
-```
-
-Finally, build the `geth` program using the following command.
-```shell
-cd go-ethereum
-make geth
-```
-
-You can now run `build/bin/geth` to start your node.

docs/_doc/Installation-instructions-for-Windows.md

@@ -1,66 +0,0 @@
----
-title: Installation instructions for Windows
----
-# Binaries
-
-## Download stable binaries
-
-All versions of Geth are built and available for download at https://geth.ethereum.org/downloads/.
-
-The download page provides an installer as well as a zip file. The installer puts geth into your
-PATH automatically. The zip file contains the command .exe files and can be used without installing.
-
-1. Download zip file
-1. Extract geth.exe from zip
-1. Open a command prompt
-1. chdir <path to geth.exe>
-1. open geth.exe
-
-# Source
-
-## Compiling geth with tools from chocolatey
-
-The Chocolatey package manager provides an easy way to get
-the required build tools installed. If you don't have chocolatey yet,
-follow the instructions on https://chocolatey.org to install it first.
-
-Then open an Administrator command prompt and install the build tools
-we need:
-
-```text
-C:\Windows\system32> choco install git
-C:\Windows\system32> choco install golang
-C:\Windows\system32> choco install mingw
-``` 
-
-Installing these packages will set up the `Path` environment variable.
-Open a new command prompt to get the new `Path`. The following steps don't
-need Administrator privileges.
-
-Please ensure that the installed Go version is 1.7 (or any later version).
-
-First we'll create and set up a Go workspace directory layout,
-then clone the source.
-
-***OBS*** If, during the commands below, you get the following message: 
-```
- WARNING: The data being saved is truncated to 1024 characters.
-```
-Then that means that the `setx` command will fail, and proceeding will truncate the `Path`/`GOPATH`. If this happens, it's better to abort, and try to make some more room in `Path` before trying again. 
-
-```text
-C:\Users\xxx> set "GOPATH=%USERPROFILE%"
-C:\Users\xxx> set "Path=%USERPROFILE%\bin;%Path%"
-C:\Users\xxx> setx GOPATH "%GOPATH%"
-C:\Users\xxx> setx Path "%Path%"
-C:\Users\xxx> mkdir src\github.com\ethereum
-C:\Users\xxx> git clone https://github.com/ethereum/go-ethereum src\github.com\ethereum\go-ethereum
-C:\Users\xxx> cd src\github.com\ethereum\go-ethereum
-C:\Users\xxx> go get -u -v golang.org/x/net/context
-```
-
-Finally, the command to compile geth is:
-
-```text
-C:\Users\xxx\src\github.com\ethereum\go-ethereum> go install -v ./cmd/...
-```

docs/_install-and-build/Building-Ethereum.md

@@ -1,22 +1,22 @@
 ---
-title: Building Ethereum
+title: Building Geth
 ---
 ## Installation Instructions
 
 Follow the appropriate link below to find installation instructions for
 your platform.
 
-* [Installation Instructions for Mac OS X](../doc/Installation-Instructions-for-Mac)
-* [Installation Instructions for Windows](../doc/Installation-instructions-for-Windows)
+* [Installation Instructions for Mac OS X](Installation-Instructions-for-Mac)
+* [Installation Instructions for Windows](Installing-Geth)
 * Installation Instructions for Linux/Unix
-  * [Ubuntu](../doc/Installation-Instructions-for-Ubuntu)
-  * [Arch](../doc/Installation-Instructions-for-Arch)
-  * [FreeBSD](../doc/Installation-Instructions-for-FreeBSD)
+  * [Ubuntu](Installing-Geth)
+  * [Arch](Installation-Instructions-for-Arch)
+  * [FreeBSD](Installation-Instructions-for-FreeBSD)
 * [Setup for Raspberry Pi](https://github.com/ethereum/wiki/wiki/Raspberry-Pi-instructions)
- *  [ARM](../doc/Installation-Instructions-for-ARM)
-* [Usage instructions for Docker](../doc/Running-in-Docker)
+ *  [ARM](Installation-Instructions-for-ARM)
+* [Usage instructions for Docker](Running-in-Docker)
 
 ## Quick Links
 
 * [Ubuntu PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum)
-* [Download Page](https://geth.ethereum.org/downloads)
+* [Download Page](https://geth.ethereum.org/downloads)

docs/_interface/JavaScript-Console.md

@@ -14,7 +14,7 @@ The `ethereum CLI` executable `geth` has a JavaScript console (a **Read, Evaluat
 
 The attach node accepts an endpoint in case the geth node is running with a non default ipc endpoint or you would like to connect over the rpc interface.
 
-    $ geth attach ipc:/some/custom/path
+    $ geth attach /some/custom/path.ipc
     $ geth attach http://191.168.1.1:8545
     $ geth attach ws://191.168.1.1:8546
 
@@ -26,7 +26,7 @@ If you need log information, start with:
 
 Otherwise mute your logs, so that it does not pollute your console:
 
-    $ geth console 2>> /dev/null
+    $ geth console 2> /dev/null
 
 or 
 
@@ -59,7 +59,7 @@ You can exit the console cleanly by typing `exit` or simply with `CTRL-C`.
 
 The go-ethereum JSRE uses the [Otto JS VM](https://github.com/robertkrimen/otto) which has some limitations:
 
-* "use strict" will parse, but does nothing.
+* `"use strict"` will parse, but does nothing.
 * The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 specification.
 
 Note that the other known limitation of Otto (namely the lack of timers) is taken care of. Ethereum JSRE implements both `setTimeout` and `setInterval`. In addition to this, the console provides `admin.sleep(seconds)` as well as a "blocktime sleep" method `admin.sleepBlocks(number)`. 

docs/_support/FAQ.md

@@ -1,17 +1,19 @@
 ---
 title: FAQ
 ---
-***
+
 **Q.**  I noticed my peercount slowly decrease, and now it is at 0.  Restarting doesn't get any peers.
 
 **A.**  Check and sync your clock with ntp.  [Example](http://askubuntu.com/questions/254826/how-to-force-a-clock-update-using-ntp) `sudo ntpdate -s time.nist.gov`
 
-***
+---
 
 **Q.**  I would like to run multiple geth instances but got the error "Fatal: blockchain db err: resource temporarily unavailable".
 
 **A.**  Geth uses a datadir to store the blockchain, accounts and some additional information. This directory cannot be shared between running instances. If you would like to run multiple instances follow [these](../doc/Setting-up-private-network-or-local-cluster) instructions.
 
+---
+
 **Q.** How do Ethereum syncing work?
 
 **A.** The current default mode of sync for Geth is called fast sync. Instead of starting from the genesis block and reprocessing all the transactions that ever occurred (which could take weeks), fast sync downloads the blocks, and only verifies the associated proof-of-works. Downloading all the blocks is a straightforward and fast procedure and will relatively quickly reassemble the entire chain.
@@ -22,7 +24,9 @@ So, what's the state trie? In the Ethereum mainnet, there are a ton of accounts
 
 Ok, so why does this pose a problem? This trie data structure is an intricate interlink of hundreds of millions of tiny cryptographic proofs (trie nodes). To truly have a synchronized node, you need to download all the account data, as well as all the tiny cryptographic proofs to verify that noone in the network is trying to cheat you. This itself is already a crazy number of data items. The part where it gets even messier is that this data is constantly morphing: at every block (15s), about 1000 nodes are deleted from this trie and about 2000 new ones are added. This means your node needs to synchronize a dataset that is changing 200 times per second. The worst part is that while you are synchronizing, the network is moving forward, and state that you begun to download might disappear while you're downloading, so your node needs to constantly follow the network while trying to gather all the recent data. But until you actually do gather all the data, your local node is not usable since it cannot cryptographically prove anything about any accounts.
 
-If you see that you are 64 blocks behind mainnet, you aren't yet synchronized, not even close. You are just done with the block download phase and still running the state downloads. You can see this yourself via the seemingly endless Imported state entries [...] stream of logs. You'll need to wait that out too before your node comes truly online.
+If you see that you are 64 blocks behind mainnet, you aren't yet synchronized, not even close. You are just done with the block download phase and still running the state downloads. You can see this yourself via the seemingly endless `Imported state entries [...]` stream of logs. You'll need to wait that out too before your node comes truly online.
+
+---
 
 **Q: The node just hangs on importing state enties?!**
 
@@ -30,10 +34,14 @@ If you see that you are 64 blocks behind mainnet, you aren't yet synchronized, n
 
 The reason is that a block in Ethereum only contains the state root, a single hash of the root node. When the node begins synchronizing, it knows about exactly 1 node and tries to download it. That node, can refer up to 16 new nodes, so in the next step, we'll know about 16 new nodes and try to download those. As we go along the download, most of the nodes will reference new ones that we didn't know about until then. This is why you might be tempted to think it's stuck on the same numbers. It is not, rather it's discovering and downloading the trie as it goes along.
 
+---
+
 **Q: I'm stuck at 64 blocks behind mainnet?!**
 
 *A:* As explained above, you are not stuck, just finished with the block download phase, waiting for the state download phase to complete too. This latter phase nowadays take a lot longer than just getting the blocks.
 
+---
+
 **Q: Why does downloading the state take so long, I have good bandwidth?**
 
 **A:** State sync is mostly limited by disk IO, not bandwidth.
@@ -42,8 +50,10 @@ The state trie in Ethereum contains hundreds of millions of nodes, most of which
 
 Not only is storing the data very suboptimal, but due to the 200 modification / second and pruning of past data, we cannot even download it is a properly pre-processed way to make it import faster without the underlying database shuffling it around too much. The end result is that even a fast sync nowadays incurs a huge disk IO cost, which is too much for a mechanical hard drive.
 
+---
+
 **Q: Wait, so I can't run a full node on an HDD?**
 
 **A:** Unfortunately not. Doing a fast sync on an HDD will take more time than you're willing to wait with the current data schema. Even if you do wait it out, an HDD will not be able to keep up with the read/write requirements of transaction processing on mainnet.
 
-You however should be able to run a light client on an HDD with minimal impact on system resources. If you wish to run a full node however, an SSD is your only option.
+You however should be able to run a light client on an HDD with minimal impact on system resources. If you wish to run a full node however, an SSD is your only option.

docs/_whisper/Whisper-Overview.md

@@ -1,7 +1,6 @@
 ---
 title: Overview
 ---
-## Whisper Overview
 
 Whisper is a pure identity-based messaging system. Whisper provides a simple low-level API without being based upon or influenced by the low-level hardware attributes and characteristics. Peer-to-peer communication between the nodes of Whisper network uses the underlying [ÐΞVp2p Wire Protocol](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol). Whisper was not designed to provide a connection-oriented system, nor for simply delivering data between a pair of particular network endpoints. However, this might be necessary in some very specific cases (e.g. delivering the expired messages in case they were missed), and Whisper protocol will accommodate for that. Whisper is designed for easy and efficient broadcasting, and also for low-level asynchronous communications. It is designed to be a building block in next generation of unstoppable ÐApps. It was designed to provide resilience and privacy at considerable expense. At its most secure mode of operation, Whisper can theoretically deliver 100% darkness. Whisper should also allow the users to configure the level of privacy (how much information it leaks concerning the ÐApp content and ultimately, user activities) as a trade-off for performance.