Ensure sphinx documentation builders to not interpret some docstrings as section headers.

.circleci/validate-hook.sh

@@ -8,4 +8,4 @@ if ! eMSG=$(circleci config validate -c .circleci/config.yml); then
 	echo "CircleCI Configuration Failed Validation."
 	echo $eMSG
 	exit 1
-fi
+fi

nucypher/blockchain/economics.py

@@ -33,8 +33,6 @@ class BaseEconomics:
     A representation of a contract deployment set's constructor parameters, and the calculations
     used to generate those values from high-level human-understandable parameters.
 
-    --------------------------
-
     Formula for staking in one period:
     (totalSupply - currentSupply) * (lockedValue / totalLockedValue) * (k1 + allLockedPeriods) / k2
 
@@ -250,7 +248,6 @@ class BaseEconomics:
 
 class StandardTokenEconomics(BaseEconomics):
     """
-    --------------------------
 
     Formula for staking in one period:
     (totalSupply - currentSupply) * (lockedValue / totalLockedValue) * (k1 + allLockedPeriods) / k2
@@ -266,8 +263,6 @@ class StandardTokenEconomics(BaseEconomics):
     kappa = small_stake_multiplier + (1 - small_stake_multiplier) * min(T, T1) / T1
     where allLockedPeriods == min(T, T1)
 
-    --------------------------
-
     Academic Reference:
 
     NuCypher: Mining & Staking Economics - Michael Egorov, MacLane Wilkison, NuCypher

nucypher/blockchain/eth/agents.py

@@ -613,8 +613,10 @@ class StakingEscrowAgent(EthereumContractAgent):
         at least `duration` periods; a staker is selected if an input point is within its stake.
         For example:
 
+        ```
         Stakes: |----- S0 ----|--------- S1 ---------|-- S2 --|---- S3 ---|-S4-|----- S5 -----|
         Points: ....R0.......................R1..................R2...............R3...........
+        ```
 
         In this case, Stakers 0, 1, 3 and 5 will be selected.
 

nucypher/blockchain/eth/clients.py

@@ -120,8 +120,7 @@ class EthereumClient:
     def from_w3(cls, w3: Web3) -> 'EthereumClient':
         """
 
-        Client version strings
-        ======================
+        Client version strings:
 
         Geth    -> 'Geth/v1.4.11-stable-fed692f6/darwin/go1.7'
         Parity  -> 'Parity-Ethereum/v2.5.1-beta-e0141f8-20190510/x86_64-linux-gnu/rustc1.34.1'

nucypher/config/base.py

@@ -17,40 +17,37 @@ class BaseConfiguration(ABC):
     and restoring a subclass instance from the written JSON file by passing the deserialized
     values to the subclass's constructor.
 
-    Implementation
-    ==============
+    Implementation:
 
-    `_NAME` and `def static_payload` are required for subclasses, for example:
+    `NAME` and `def static_payload` are required for subclasses, for example:
 
+    .. code::
 
-        ```
         class MyItem(BaseConfiguration):
             _NAME = 'my-item'
 
-        ```
-        AND
+    AND
+
+    .. code::
 
-        ```
         def static_payload(self) -> dict:
             payload = dict(**super().static_payload(), key=value)
             return payload
-        ```
 
-        OR
+    OR
+
+    .. code::
 
-        ```
         def static_payload(self) -> dict:
             subclass_payload = {'key': 'value'}
             payload = {**super().static_payload(), **subclass_payload}
             return payload
-        ```
 
     Filepath Generation
-    ===================
 
     Default behavior *avoids* overwriting an existing configuration file:
 
-    - The name of the JSON file to write/read from is determined by `_NAME`.
+    - The name of the JSON file to write/read from is determined by `NAME`.
       When calling `to_configuration_file`.
 
     - If the default path (i.e. `my-item.json`) already  exists and, optionally,
@@ -61,12 +58,11 @@ class BaseConfiguration(ABC):
     If the subclass implementation has a global unique identifier, an additional method override
     to `to_configuration_file` will automate the renaming process.
 
-        ```
+    .. code::
+
         def to_configuration_file(*args, **kwargs) -> str:
             filepath = super().to_configuration_file(modifier=<MODIFIER>, *args, **kwargs)
             return filepath
-        ```
-
     """
 
     _NAME = NotImplemented