Merge pull request #1352 from cygnusv/docs-rst

Fixes broken formatting in the docs
2019-09-23 16:05:44 +02:00 · 2019-09-23 16:05:44 +02:00 · c11e4a247c
parent 673aa13b81 ee210d956f
commit c11e4a247c
12 changed files with 55 additions and 38 deletions
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@ -497,7 +497,7 @@ jobs:
  build_docs:
    <<: *python_37_base
    steps:
-      - checkout
+      - prepare_environment
      - run:
          name: Install Documentation Build Dependencies
          command: pip3 install --user sphinx recommonmark sphinx-rtd-theme aafigure
--- a/README.md
+++ b/README.md
@ -19,7 +19,7 @@ There are no gate-keepers and anyone can use it.
 * Intuitive - The network leverages the classic cryptological narrative of Alice and Bob
 (with additional characters where appropriate). This character-based narrative permeates the code-base and helps
 developers write safe, misuse-resistant code.
-* Extensible - The network currently supports proxy re-encryption but can be extended to provide support other cryptographic primitives.
+* Extensible - The network currently supports proxy re-encryption but can be extended to provide support for other cryptographic primitives.

 Access permissions are baked into the underlying encryption,
 and access can only be explicitly granted by the data owner via sharing policies.
--- a/docs/Makefile
+++ b/docs/Makefile
@ -2,7 +2,7 @@
 #

 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = python3 -m sphinx
 SOURCEDIR     = source
 BUILDDIR      = build
--- a/docs/source/api/policy.rst
+++ b/docs/source/api/policy.rst
@ -1,5 +1,5 @@
 Policy
 ======

-.. automodule:: nucypher.policy.models
+.. automodule:: nucypher.policy.policies
    :members:
--- a/docs/source/architecture/contracts.md
+++ b/docs/source/architecture/contracts.md
@ -14,6 +14,9 @@

 ## Deployment Procedure

+This section provides a step-by-step guide of how NuCypher contracts are deployed.
+For a guide of how to deploy these contracts automatically, see the [Deployment guide](/guides/deployment_guide).
+
 1. Deploy `NuCypherToken` with all future supply tokens
 2. Deploy `StakingEscrow` with a dispatcher targeting it
 3. Deploy `PolicyManager` with its own dispatcher, also targeting it
@ -56,10 +59,10 @@ Execution of these methods results in Alice recovering all fees for future perio
 Alice can refund ETH for any inactive periods without revoking the policy by using the method `PolicyManager.refund(bytes16)` or `PolicyManager.refund(bytes16, address)`.


-## Ursula's Contract Interaction
+## Staker's Contract Interaction


-### Ursula Locks Tokens
+### Staker Locks Tokens

 In order to become a participant of the network, a staker stakes tokens in the `StakingEscrow` contract.
 The staker allows the (staking) contract to perform a transaction using the `NuCypherToken.approve(address, uint256)` method
@ -82,9 +85,15 @@ The first parameter is used to identify the stake to divide and the last two for
 When calculating locked tokens using the `StakingEscrow.getLockedTokens(address, uint16)` method, all stakes that are active during the specified period are summed.


+### The Staker Bonds to a Worker ("Ursula")
+The staker must specify a worker who will confirm the activity and sign on behalf of this staker by calling the `StakingEscrow.setWorker(address)` method.
+Changing a worker is allowed no more than once within `StakingEscrow.minWorkerPeriods()`.
+Only the worker can confirm activity.
+
+
 ### Ursula Confirms Activity

-In order to confirm activity every period, stakers call `StakingEscrow.confirmActivity()` wherein activities for the next period are registered.
+In order to confirm activity every period, workers call `StakingEscrow.confirmActivity()` wherein activities for the next period are registered.
 The staker gets a reward for every confirmed period.

 ### Ursula Generates Staking Rewards
@ -110,10 +119,6 @@ The staker can set a minimum reward rate for a policy. For that, the staker shou
 Some users will have locked but not staked tokens.
 In that case, an instance of the `UserEscrow` contract will hold their tokens (method `UserEscrow.initialDeposit(uint256, uint256)`).
 All tokens will be unlocked after a specified time and the user can retrieve them using the `UserEscrow.withdraw(uint256)` method.
-When the user wants to become a staker - he uses the `UserEscrow` contract as a proxy for the `StakingEscrow` and `PolicyManager` contracts.
+When the user wants to become a staker - they use the `UserEscrow` contract as a proxy for the `StakingEscrow` and `PolicyManager` contracts.


-### Ursula's Worker
-The staker must specify a worker who will confirm the activity and sign on behalf of this staker by calling the `StakingEscrow.setWorker(address)` method.
-Changing a worker is allowed no more than 1 time in `StakingEscrow.minWorkerPeriods()`.
-Only the worker can confirm activity.
--- a/docs/source/demos/local_fleet_demo.rst
+++ b/docs/source/demos/local_fleet_demo.rst
@ -18,7 +18,7 @@ All Demo Ursulas:
 * Using temporary resources (files, database, etc.)


-Running A Local Fleet
+Running a Local Fleet
 ---------------------

 1. Install NuCypher
--- a/docs/source/guides/contribution_guide.rst
+++ b/docs/source/guides/contribution_guide.rst
@ -21,7 +21,7 @@ Here is the recommended procedure for acquiring the code in preparation for
 contributing proposed changes:


-1. Use GitHub to Fork the `nucypher/nucypher` repository
+1. Use GitHub to fork the ``nucypher/nucypher`` repository

 2. Clone your fork's repository to your local machine

@ -29,19 +29,19 @@ contributing proposed changes:

   $ git clone https://github.com/<YOUR-GITHUB-USERNAME>/nucypher.git

-3. Change Directories into ``nucypher``
+3. Change directory to ``nucypher``

 .. code-block:: bash

-   cd nucypher
+   $ cd nucypher

-3. Add `nucypher/nucypher` as an upstream remote
+4. Add ``nucypher/nucypher`` as an upstream remote

 .. code-block:: bash

   $ git remote add upstream https://github.com/nucypher/nucypher.git

-4. Update your remote tracking branches
+5. Update your remote tracking branches

 .. code-block:: bash

@ -49,7 +49,7 @@ contributing proposed changes:

 .. _`Developer Installation Guide`: https://docs.nucypher.com/en/latest/guides/installation_guide.html

-5. Install the project dependencies: see the `Developer Installation Guide`_
+6. Install the project dependencies: see the `Developer Installation Guide`_


 Running the Tests
@ -81,7 +81,7 @@ Optionally, to run the full, slow, verbose test suite run:
  (nucypher)$ pytest --runslow -s


-Making A Commit
+Making a Commit
 ---------------

 NuCypher takes pride in its commit history.
@ -98,10 +98,10 @@ are first-time contributors to open source, so feel free to join our `Discord <h
 how we can best support the submission of your proposed changes.


-Opening A Pull Request
+Opening a Pull Request
 ----------------------

-When considering including commits as part of a pull request into `nucypher/nucypher`,
+When considering including commits as part of a pull request into ``nucypher/nucypher``,
 we *highly* recommend opening the pull request early, before it is finished with
 the mark "[WIP]" prepended to the title.  We understand PRs marked "WIP" to be subject to change,
 history rewrites, and CI failures. Generally we will not review a WIP PR until the "[WIP]" marker
@ -129,7 +129,7 @@ Generally speaking the preferred process of doing so is with an `interactive reb
   $ git remote update
   ...  (some upstream changes are reported)

-2. Initiate an interactive rebase over `nucypher/nucypher@master`
+2. Initiate an interactive rebase over ``nucypher/nucypher@master``

 .. note::

--- a/docs/source/guides/deployment_guide.rst
+++ b/docs/source/guides/deployment_guide.rst
@ -1,3 +1,8 @@
+..
+   TODO: #1354 - Find a home for this guide
+
+:orphan:
+
 =================
 Deployment Guide
 =================
--- a/docs/source/guides/federated_testnet_guide.rst
+++ b/docs/source/guides/federated_testnet_guide.rst
@ -1,3 +1,8 @@
+..
+   TODO: #1354 - Find a home for this guide
+
+:orphan:
+
 =============================================
 NuCypher Federated Testnet (NuFT) Setup Guide
 =============================================
--- a/docs/source/guides/installation_guide.md
+++ b/docs/source/guides/installation_guide.md
@ -154,8 +154,8 @@ $ ./scripts/installation/install_solc.sh

 ## Systemd Service Installation

-1. Use this template to create a file named _ursula.service_ and place it in */etc/systemd/system/*.
-
+1. Use this template to create a file named `ursula.service` and place it in `/etc/systemd/system/`.
+ 
    ```
    [Unit]
    Description="Run 'Ursula', a NuCypher Staking Node."
--- a/docs/source/guides/staking_guide.rst
+++ b/docs/source/guides/staking_guide.rst
@ -43,7 +43,7 @@ All staking-related operations done by StakeHolder are performed through the ``n
 +----------------------+-------------------------------------------------------------------------------+
 |  ``divide``          | Create a new stake from part of an existing one                               |
 +----------------------+-------------------------------------------------------------------------------+
-|  ``restake``          | Manage automatic reward re-staking                                            |
+|  ``restake``         | Manage automatic reward re-staking                                            |
 +----------------------+-------------------------------------------------------------------------------+

 **Stake Command Options**
@ -60,7 +60,7 @@ All staking-related operations done by StakeHolder are performed through the ``n
 | ``--hw-wallet`` | Use a hardware wallet                      |
 +-----------------+--------------------------------------------+

-**ReStake Command Options**
+**Re-stake Command Options**

 +-------------------------+---------------------------------------------+
 | Option                  |  Description                                |
@ -79,7 +79,7 @@ Staking Overview

 Most stakers on the Goerli testnet will complete the following steps:

-1) Install nucypher on StakeHolder node https://docs.nucypher.com/en/latest/guides/installation_guide.html
+1) Install ``nucypher`` on StakeHolder node (See :doc:`/guides/installation_guide`)
 2) Install and run Geth, Parity or another ethereum node (can be used with software or hardware Ethereum wallet).
 3) Request testnet tokens from faucet
 4) Stake tokens (See Below)
@ -91,7 +91,7 @@ Most stakers on the Goerli testnet will complete the following steps:
 Interactive Method
 ------------------

-Run an Ethereum node for stakeholder
+Run an Ethereum node for Stakeholder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Assuming you have ``geth`` installed, let's run a node on Görli testnet.
@ -242,6 +242,7 @@ in the address. However, geth shows addresses in the lower case. You can convert
 the address to checksum format in geth console:

 .. code:: bash
+
    $ geth attach ~/.ethereum/goerli/geth.ipc
    > eth.accounts
    ["0x287a817426dd1ae78ea23e9918e2273b6733a43d", "0xc080708026a3a280894365efd51bb64521c45147"]
@ -262,22 +263,22 @@ to enable it run:

    (nucypher)$ nucypher stake restake --enable

-To disable restaking:
+To disable re-staking:

 .. code:: bash

    (nucypher)$ nucypher stake restake --disable


-Additionally, you can enable **restake locking**, an on-chain commitment to continue restaking
+Additionally, you can enable **re-stake locking**, an on-chain commitment to continue re-staking
 until a future period (`release_period`). Once enabled, the `StakingEscrow` contract will not
-allow **restaking** to be disabled until the release period begins, even if you are the stake owner.
+allow **re-staking** to be disabled until the release period begins, even if you are the stake owner.

 .. code:: bash

    (nucypher)$ nucypher stake restake --lock-until 12345

-No action is needed to release the restaking lock once the release period begins.
+No action is needed to release the re-staking lock once the release period begins.


 Collect rewards earned by the staker
@ -291,7 +292,7 @@ fees, or both:

 .. code:: bash

-    nucypher stake collect-reward --staking-reward --policy-reward --staking-address 0x287A817426DD1AE78ea23e9918e2273b6733a43D --hw-wallet
+    (nucypher)$ nucypher stake collect-reward --staking-reward --policy-reward --staking-address 0x287A817426DD1AE78ea23e9918e2273b6733a43D --hw-wallet

     ____    __            __
    /\  _`\ /\ \__        /\ \
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@ -32,12 +32,13 @@ NuCypher
 .. _Umbral: https://github.com/nucypher/pyUmbral

 The NuCypher network provides accessible, intuitive, and extensible runtimes and interfaces for secrets management and dynamic access control.
+
 * Accessible - The network is permissionless and censorship-resistant.
-There are no gate-keepers and anyone can use it.
+  There are no gate-keepers and anyone can use it.
 * Intuitive - The network leverages the classic cryptological narrative of Alice and Bob
-(with additional characters where appropriate). This character-based narrative permeates the code-base and helps
-developers write safe, misuse-resistant code.
-* Extensible - The network currently supports proxy re-encryption but can be extended to provide support other cryptographic primitives.
+  (with additional characters where appropriate). This character-based narrative permeates the code-base and helps
+  developers write safe, misuse-resistant code.
+* Extensible - The network currently supports proxy re-encryption but can be extended to provide support for other cryptographic primitives.

 Access permissions are baked into the underlying encryption,
 and access can only be explicitly granted by the data owner via sharing policies.