Merge pull request #1731 from derekpierre/docs-layout

Reorganize Docs Layout

docs/source/architecture/contracts.md

@@ -1,4 +1,4 @@
-# NuCypher Ethereum Contracts
+# Ethereum Contracts
 
 
 ## Contract Listing

docs/source/architecture/sub_stakes.rst

@@ -150,6 +150,8 @@ Slashing
 Flags that affect the sub-stake array
 -------------------------------------
 
+.. _sub-stake-restaking:
+
 Re-staking
 ^^^^^^^^^^
 *Used in methods* : ``confirmActivity()``, ``mint()``

docs/source/architecture/upgradeable_proxy_contracts.rst

@@ -1,5 +1,5 @@
-NuCypher's Approaches to Upgradeable Contracts
+Approaches to Upgradeable Contracts
-==============================================
+===================================
 
 Smart contracts in Ethereum are immutable...
 In order to fix bugs and provide upgrade logic it is possible to change the contract (address) and save the original contract's storage values.

docs/source/guides/development/character_control_guide.rst

@@ -1,6 +1,6 @@
-================================
+=======================
-NuCypher Character Control Guide
+Character Control Guide
-================================
+=======================
 
 The `Character Control` is a module that contains useful REST-like HTTP endpoints for working with NuCypher characters.
 

docs/source/guides/development/cli_guide.rst

@@ -1,6 +1,6 @@
-==================
+=========
-NuCypher CLI Guide
+CLI Guide
-==================
+=========
 
 Overview
 --------
@@ -11,7 +11,7 @@ Overview
 
 This guide is an example of NuCypher's decentralized network allowing Alice to share a secret
 with Bob using the NuCypher Network via the ``nucypher`` CLI. It is analogous to the ``python`` example
-in :doc:`/guides/getting_started`.
+in :doc:`getting_started`.
 
 To better understand the commands and their options, use the ``--help`` option.
 

docs/source/guides/development/development.rst

@@ -0,0 +1,12 @@
+=======================
+Application Development
+=======================
+
+The NuCypher Network provides cryptographic infrastructure for privacy-preserving applications.
+
+.. toctree::
+   :maxdepth: 1
+
+   getting_started
+   cli_guide
+   character_control_guide

docs/source/guides/development/getting_started.md

@@ -141,7 +141,7 @@ alice = Alice(known_nodes=[ursula, another_ursula], ...)
 ```
 
 For information on how to run a staking Ursula node via CLI,
-see <https://docs.nucypher.com/en/latest/guides/staking_guide.html>
+see [Running a Network Node](/guides/network_node/network_node).
 
 ## Alice: Grant Access to a Secret
 

docs/source/guides/installation_guide.md

@@ -140,7 +140,7 @@ Here is the recommended procedure for setting up `nucypher` in this fashion:
      docker run -it -v ~/.local/share/nucypher:/root/.local/share/nucypher -v ~/.ethereum/:/root/.ethereum -p 9151:9151 nucypher/nucypher:latest nucypher status network --provider <PROVIDER URI> --network <NETWORK NAME>
     
         
-  Running a pre-configured Worker as a daemon (See [Configuration Guide](/guides/ursula_configuration_guide)):
+  Running a pre-configured Worker as a daemon (See [Configuration Guide](/guides/network_node/ursula_configuration_guide)):
  
      docker run -d -v ~/.local/share/nucypher:/root/.local/share/nucypher -v ~/.ethereum/:/root/.ethereum -p 9151:9151 -e NUCYPHER_KEYRING_PASSWORD -e NUCYPHER_WORKER_ETH_PASSWORD nucypher/nucypher:latest nucypher ursula run
 

docs/source/guides/network_node/network_node.rst

@@ -0,0 +1,11 @@
+======================
+Running a Network Node
+======================
+
+To be a node on the NuCypher network, operations are divided into two roles “Staker” and “Worker”.
+
+.. toctree::
+   :maxdepth: 1
+
+   staking_guide
+   ursula_configuration_guide

docs/source/guides/network_node/staking_guide.rst

@@ -1,8 +1,8 @@
 .. _staking-guide:
 
-=======================
+==========================
-NuCypher Staking Guide
+Staker Configuration Guide
-=======================
+==========================
 
 NuCypher staking operations are divided into two roles "Staker" and "Worker" - This Guide is for Stakers.
 
@@ -29,7 +29,7 @@ Staking Procedure:
 6) Create and fund worker's ethereum address with ETH
 7) Bond a Worker to a Staker using the worker's ethereum address (see `Bonding a Worker`_)
 8) Optionally, modify stake settings (see `Modifying Active Stakes`_)
-9) Configure and Run a Worker Node (see :doc:`/guides/ursula_configuration_guide`)
+9) Configure and Run a Worker Node (see :ref:`ursula-config-guide`)
 
 
 Staking CLI
@@ -338,6 +338,8 @@ allow **re-staking** to be disabled until the release period begins, even if you
 No action is needed to release the re-staking lock once the release period begins.
 
 
+.. _staking-prolong:
+
 Prolong
 *******
 

docs/source/guides/network_node/ursula_configuration_guide.rst

@@ -1,8 +1,8 @@
 .. _ursula-config-guide:
 
-==========================
+===================================
-Ursula Configuration Guide
+Worker (Ursula) Configuration Guide
-==========================
+===================================
 
 NuCypher staking operations are divided into two roles "Staker" and "Worker" - This Guide is for Workers.
 
@@ -21,7 +21,7 @@ Working Procedure:
 
 .. References are needed for links because of the numbers in the section names
 
-1) Ensure that a `Stake` is available (see :doc:`/guides/staking_guide`)
+1) Ensure that a `Stake` is available (see :ref:`staking-guide`)
 2) Run an ethereum node on the Worker's machine eg. geth, parity, etc. (see :ref:`Running an Ethereum node for Ursula <running-worker-eth-node>`)
 3) Install ``nucypher`` on Worker node (see :doc:`/guides/installation_guide`)
 4) Create and fund worker's ethereum address (see :ref:`Fund Worker Account with ETH <fund-worker-account>`)
@@ -183,6 +183,8 @@ To stop your node from the interactive console and return to the terminal sessio
     Ursula >>> stop
 
 
+.. _run-ursula-with-docker:
+
 Running an Ursula with Docker
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/guides/worklock_guide.rst

@@ -1,13 +1,18 @@
-=======================
+==============
-NuCypher WorkLock Guide
+WorkLock Guide
-=======================
+==============
 
 Overview
 --------
 
-TODO
+`WorkLock` is a novel, permissionless token distribution mechanism, developed at NuCypher, which requires participants to stake ETH and maintain NuCypher nodes in order to receive NU tokens.
 
-To better understand the commands and their options, use the ``--help`` option.
+WorkLock offers specific advantages over ICO or airdrop as a distribution mechanism, chiefly: it selects for participants who are most likely to strengthen the network because they commit to staking and running nodes.
+
+The WorkLock begins with an open bidding period, during which anyone seeking to participate can send ETH to the WorkLock contract to be escrowed on-chain.  At the end of the bidding period, stake-locked NU will be distributed pro rata across contributors. If those contributors use that stake-locked NU to run a node, the NU will eventually unlock and their escrowed ETH will be returned in full. Alternatively, WorkLock participants can cancel their bid to forgo NU and recoup their escrowed ETH immediately.
+
+The ``nucypher worklock`` CLI command provides the ability to participate in WorkLock. To better understand the
+commands and their options, use the ``--help`` option.
 
 Common CLI flags
 ----------------

docs/source/index.rst

@@ -115,7 +115,7 @@ Whitepapers
 
 .. warning::
 
-   NuCypher is currently in the *Alpha* development stage and is **not** intended for use in production.
+   NuCypher is currently in the *Beta* development stage and is **not** intended for use in production.
 
 
 .. toctree::
@@ -123,12 +123,9 @@ Whitepapers
    :caption: Guides
 
    guides/installation_guide
-   guides/getting_started
+   guides/network_node/network_node
-   guides/staking_guide
+   guides/development/development
-   guides/ursula_configuration_guide
-   guides/cli_guide
    guides/worklock_guide
-   guides/character_control_guide
    guides/contribution_guide
 
 .. toctree::

docs/source/support/faq.rst

@@ -87,7 +87,7 @@ This is **ONLY** a heuristic to ensure that your node is running correctly, it d
 What's the best way to run Ursula in the background?
 ----------------------------------------------------
 
-Either through `Docker <https://docs.nucypher.com/en/latest/guides/ursula_configuration_guide.html#running-an-ursula-with-docker>`_
+Either through :ref:`Docker <run-ursula-with-docker>`
 or `systemd <https://docs.nucypher.com/en/latest/guides/installation_guide.html#systemd-service-installation>`_.
 
 
@@ -117,7 +117,7 @@ are in Period 5 when you start staking:
 
 .. note::
 
-    `Restaking <https://docs.nucypher.com/en/latest/architecture/sub_stakes.html#re-staking>`_ is enabled by
+    :ref:`Restaking <sub-stake-restaking>` is enabled by
     default, so NU inflation rewards are automatically restaked for you, and will be reflected in
     the ``Staked`` value of the above command.
 
@@ -136,15 +136,15 @@ Run::
 Can I extend the duration of my existing stake?
 --------------------------------------------------------------
 
-Yes, via the `prolong <https://docs.nucypher.com/en/latest/guides/staking_guide.html#prolong>`_ command.
+Yes, via the :ref:`prolong <staking-prolong>` command.
 
 
 How can I reuse an Ursula that was connected to the previous version of the testnet?
 ------------------------------------------------------------------------------------
 
 #. Run ``nucypher ursula destroy`` to destroy the current configuration.
-#. Repeat all of the steps with the new tokens in the `Staking Guide <https://docs.nucypher.com/en/latest/guides/staking_guide.html>`_.
+#. Repeat all of the steps with the new tokens in the :ref:`staking-guide`.
-#. Run ``nucypher ursula init`` per the `Ursula Configuration Guide <https://docs.nucypher.com/en/latest/guides/ursula_configuration_guide.html>`_.
+#. Run ``nucypher ursula init`` per the :ref:`ursula-config-guide`.
 
 
 What is a fleet state?

docs/source/support/troubleshooting.rst

@@ -34,7 +34,7 @@ client, this generic error will become extinct.
 
 In the most common cases:
 
-- Ensure that your worker is `bonded to a staker <https://docs.nucypher.com/en/latest/guides/staking_guide.html#bond-an-ursula-to-a-staker>`_.
+- Ensure that your worker is :ref:`bonded to a staker <bond-worker>`.
   You can confirm by running ``nucypher stake list`` and check that `Worker` is set correctly i.e. not ``0x0000``.
 - If your worker is configured, ensure that the worker address has (Goerli) ETH and that the correct worker address is
   provided in the Ursula configuration file being used - the default configuration file is ``~/.local/share/nucypher/ursula.json``