Merge pull request #75 from pipermerriam/piper/fix-warnings

Piper/fix warnings

requirements.txt

@@ -1 +1,3 @@
 restructuredtext-lint==0.14.2
+Pigments==1.6
+Sphinx==1.3.6

rst_lint.py

@@ -2,32 +2,107 @@
 import os
 import sys
 
-import restructuredtext_lint as rst_lint
-
 
 BASE_DIR = os.path.dirname(__file__)
 SOURCE_DIR = os.path.join(BASE_DIR, "source")
 
 
-def lint(dir=SOURCE_DIR):
+from docutils.core import Publisher
+from docutils.parsers.rst.directives import register_directive
+from docutils.parsers.rst import roles
+
+from sphinx.application import Sphinx
+from sphinx.domains.std import StandardDomain
+# Just importing the directives also triggers registration.
+from sphinx.directives import *  # NOQA
+
+
+sphinx = Sphinx(
+    srcdir=SOURCE_DIR,
+    confdir=SOURCE_DIR,
+    outdir=os.path.join(BASE_DIR, 'build'),
+    doctreedir=os.path.join(BASE_DIR, 'build', 'doctree'),
+    buildername='html',
+)
+
+
+class PublisherWithSphinxEnv(Publisher):
+    def get_settings(self, *args, **kwargs):
+        kwargs.setdefault('env', sphinx.env)
+        return Publisher.get_settings(self, *args, **kwargs)
+
+
+#
+# MONKEYPATCHING!!!!
+#
+# The restructuredtext_lint library uses the `Publisher` class from `docutils`
+# to generate linting errors.  Within this class, a `settings` object is
+# generated which is then passed into the various directives which produce the
+# errors and warnings.  Sphinx has some very specific needs in terms of what
+# this settings object looks like, specifically, an `env` property that needs
+# to be present.
+#
+# Here we monkeypatch the `docutils.core.Publisher` object with our own
+# subclass which includes the sphinx `env` object such that when the Sphinx
+# directives are used, they have the internals that they need available.
+from docutils import core
+core.Publisher = PublisherWithSphinxEnv
+
+# This import **MUST** occur after the `core.Publisher` monkeypatch.
+import restructuredtext_lint as rst_lint
+
+
+# The Glossary directive is special and needs to be registered on it's own.
+for role_name, role in StandardDomain.roles.items():
+    roles.register_local_role(role_name, role)
+for role_name, role in StandardDomain.directives.items():
+    register_directive(role_name, role)
+
+
+INFO = 10
+WARNING = 20
+ERROR = 30
+
+LEVELS = {
+    'INFO': INFO,
+    'WARNING': WARNING,
+    'ERROR': ERROR,
+}
+
+
+def lint(dir=SOURCE_DIR, log_level=WARNING):
     errors = []
 
     for root, subdirs, files in os.walk(SOURCE_DIR):
         for filename in files:
             extension = filename.rpartition('.')[2].lower()
             if extension == "rst":
+                abs_path = os.path.abspath(os.path.join(root, filename))
+                rel_path = os.path.relpath(abs_path, SOURCE_DIR)
+
+                # Sphinx maintains a list of `docnames` that it has found which
+                # are the relative paths to the docs from the SOURCE_DIR
+                # without the file extension.  The `sphinx.env.temp_data`
+                # dictionary needs to have the current docname populuated while
+                # it's being processed for the Sphinx directives to function
+                # properly.
+                docname = rel_path.rpartition('.')[0]
+                sphinx.env.temp_data['docname'] = docname
                 linting_errors = rst_lint.lint_file(os.path.join(root, filename))
                 if linting_errors:
                     errors.extend(linting_errors)
 
     if errors:
         for error in errors:
-            message = "{full_file_path}:{line_no}: {message}\n".format(
+            message = "{prefix}: {full_file_path}:{line_no}: {message}\n".format(
+                prefix=error.type,
                 full_file_path=os.path.relpath(error.source),
                 line_no=error.line,
                 message=error.message,
             )
-            if error.type == "WARNING":
+            if LEVELS[error.type] < log_level:
+                continue
+            elif LEVELS[error.type] < ERROR:
                 sys.stdout.write(message)
             else:
                 sys.stderr.write(message)

source/contracts-and-transactions/account-types-gas-and-transactions.rst

@@ -1,3 +1,5 @@
+.. _account-types-gas-and-transactions:
+
 ********************************************************************************
 Account Types, Gas, and Transactions
 ********************************************************************************

source/contracts-and-transactions/contracts.rst

@@ -178,20 +178,28 @@ following fields:
 
     ``code``
         The compiled EVM bytecode
+
     ``info``
         Additional metadata output from the compiler
+
     ``source``
         The source code
+
     ``language``
         The contract language (Solidity, Serpent, LLL)
+
     ``languageVersion``
         The contract language version
+
     ``compilerVersion``
         The solidity compiler version that was used to compile this contract.
+
     ``abiDefinition``
         The `Application Binary Interface Definition <https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI>`__
+
     ``userDoc``
         The `NatSpec Doc <https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format>`__ for users.
+
     ``developerDoc``
         The `NatSpec Doc <https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format>`__ for developers.
 
@@ -280,7 +288,7 @@ Now all the function calls specified in the ABI are made available on the
 contract instance. You can just call those methods on the contract instance
 in one of two ways.
 
-.. code-block:: 
+.. code-block:: js
 
     > myMultiply7.multiply.sendTransaction(3, {from: address})
     "0x12345"

source/developing-on-ethereum/test-networks.rst

@@ -85,7 +85,7 @@ Getting Morden Testnet Ether
 
 Two ways to obtain Morden testnet ether:
 
-- Mine using your CPU/GPU, (see `Mining`_).
+- Mine using your CPU/GPU, (see :ref:`mining`).
 - Use the `Ethereum wei faucet <https://zerogox.com/ethereum/wei_faucet>`__.
 
 .. todo::

source/ethereum-ecosystem/community.rst

@@ -1,3 +1,5 @@
+.. _community:
+
 ********************************************************************************
 Community
 ********************************************************************************
@@ -12,7 +14,7 @@ The `Ethereum subreddit`_ is the most inclusive Ethereum forum, where most of th
 
 Strictly no price discussion.
 
-Also, this is not the ideal place to ask for hands-on help or post questions you expect there are clear immediate answers to (use _`Gitter` and _`Stack Exchange` for these, respectively).
+Also, this is not the ideal place to ask for hands-on help or post questions you expect there are clear immediate answers to (use :ref:`gitter-rooms` and :ref:`stack-exchange` for these, respectively).
 
 Read the `Ethereum subreddit rules`_ before posting.
 
@@ -32,13 +34,18 @@ Further specialised subreddits (entirely  driven):
 .. _Ethinvestor: https://www.reddit.com/r/Ethinvestor/
 
 
+.. _stack-exchange:
+
 Stack Exchange
 ================================================================================
 
 With homestead we already have our very own `Ethereum Stack Exchange <http://ethereum.stackexchange.com/>`_ as part of the StackExchange network of Q&A communities. StackExchange free Q&A site where all the questions and answers preserved for posterity.
 
 This is the best  place to ask technical questions. Help your fellow etherians by answering questions and collect all the flair.
 
+
+.. _gitter-rooms:
+
 Gitter Rooms
 ================================================================================
 

source/ethereum-ecosystem/foundation.rst

@@ -14,7 +14,7 @@ Ethereum Foundation's Faces to the Community
 ---------------------------------------------------
 
 * `Official Homestead website <https://ethereum.org>`_ - main entrypoint
-* `Reddit <http://www.reddit.com/r/ethereum>`_ - see _`Community`
+* `Reddit <http://www.reddit.com/r/ethereum>`_ - see :ref:`community`
 * `Blog <http://blog.ethereum.org/>`_
 * `Twitter <http://twitter.com/ethereumproject>`_
 * `Youtube <https://www.youtube.com/user/ethereumproject>`_
@@ -28,4 +28,4 @@ Official communication from the Ethereum foundation most often comes in the form
 
 The foundation `Youtube channel <https://www.youtube.com/user/ethereumproject>`_ hosts our videos, including all talks of the developers conferences DEVCON0 and DEVCON1.
 
-For community discussion forums, see _`Community`.
+For community discussion forums, see :ref:`community`.

source/ethereum-ecosystem/infrastructure.rst

@@ -87,7 +87,7 @@ In order to obtain Ether, you need to either
 
 * become an Ethereum miner (see _`Mining`)  or
 * trade other currencies for Ether using centralised or trustless services
-* use the user friendly `Mist Ethereum Wallet <https://github.com/ethereum/mist/releases>`_ that as of Beta 6 introduced the ability to purchase ether using the `Shapeshift <https://shapeshift.io>`_ API.
+* use the user friendly `Mist Ethereum Wallet <https://github.com/ethereum/mist/releases>`_ that as of Beta 6 introduced the ability to purchase ether using the `Shapeshift`_ API.
 
 Trustless services
 --------------------------------------------------------------------------------

source/frequently-asked-questions/frequently-asked-questions.rst

@@ -5,20 +5,21 @@ Frequently Asked Questions
 
 * **I have heard of Ethereum, but what are Geth, Mist, Ethminer, Mix, and AlethOne?**
   As you already know, Ethereum is the blockchain-based smart contract platform that this Wiki describes. Akin to Bitcoin, Ethereum needs miners to solve cryptographic puzzles to confirm transactions and bring cryptocurrency into existence, nodes to witness and record any transactions/computations made and 'wallets' to initiate transactions/computations.
-    * **Geth**: This is the Go implementation of an Ethereum node, and is the basis for any interactions with the Ethereum blockchain. Running this locally will allow you to easily interact with the Ethereum blockchain.
-    * **Mist**: This is the equivalent of a web browser, but for the Ethereum platform. It acts as a GUI to display the accounts and contracts that you have or use on the Ethereum blockchain. It also allows you to create and interact with contracts in a graphical user interface without ever touching the command line. If you are not a developer and just want to store Ether and interact with Ethereum contracts, then Mist is the program to use. Latest releases can be found `here <https://github.com/ethereum/mist/releases>`_. 
-    * **AlethOne**: The mainline Ethereum desktop miner. It connects and syncs to the Ethereum network and lets you mine, and send transactions. It will also let you do pool mining.  
-    * **Ethminer**: A standalone miner. This can be used to check how fast you can mine and will mine for you in concert with eth, geth and pyethereum.
-    * **Mix**: The integrated development environment for DApp authoring. Quickly prototype and debug decentralised applications on the Ethereum platform.
+* **Geth**: This is the Go implementation of an Ethereum node, and is the basis for any interactions with the Ethereum blockchain. Running this locally will allow you to easily interact with the Ethereum blockchain.
+* **Mist**: This is the equivalent of a web browser, but for the Ethereum platform. It acts as a GUI to display the accounts and contracts that you have or use on the Ethereum blockchain. It also allows you to create and interact with contracts in a graphical user interface without ever touching the command line. If you are not a developer and just want to store Ether and interact with Ethereum contracts, then Mist is the program to use. Latest releases can be found `here <https://github.com/ethereum/mist/releases>`_. 
+* **AlethOne**: The mainline Ethereum desktop miner. It connects and syncs to the Ethereum network and lets you mine, and send transactions. It will also let you do pool mining.  
+* **Ethminer**: A standalone miner. This can be used to check how fast you can mine and will mine for you in concert with eth, geth and pyethereum.
+* **Mix**: The integrated development environment for DApp authoring. Quickly prototype and debug decentralised applications on the Ethereum platform.
 * **How can I store big files on the blockchain?**
   Swarm is an Ethereum-specific project for distributed file storage. IPFS is an independent project which has close ties to Ethereum; it will be used independently and may be used as the layer underlying Swarm.
 * **Is Ethereum based on bitcoin?**
   Only in the sense that it uses a blockchain, which Bitcoin pioneered. Ethereum has a separate blockchain that has several significant technical differences from Bitcoin's blockchain.
-* **What other cool apps are being built?** See `this <http://dapps.ethercasts.com/>`_ list from Ethercasts.
+* **What other cool apps are being built?** See `the dapp list <http://dapps.ethercasts.com/>`_ from Ethercasts.
 * **What's the future of Ethereum?** We are planning a switch to Proof of Stake_ in the near future. We are also investigating scalability_ solutions and how to store_ secrets on the blockchain
 
 * **How can I use Ethereum to get information about the future?**
   Augur and Gnosis are building prediction markets that try to gather the best information about uncertain future events. Besides that, there are also other interesting Ethereum-related projects on the market:
+
     * `Swarm <https://www.youtube.com/watch?v=VOC45AgZG5Q&index=11&list=PLJqWcTqh_zKHQUFX4IaVjWjfT2tbS4NVk>`_
     * `IPFS <http://ipfs.io>`_
     * `Ethercasts  <http://dapps.ethercasts.com/>`_
@@ -37,6 +38,8 @@ Frequently Asked Questions
 * **How long should it take to download the blockchain?** The Ethereum blockchain is constantly growing, and is nearing 7GB as of February 2016. It can take an hour or two to download. 
 
 * **How can I safely store my ether?**
+
+
 Here are the possible ways to store ether:
     * Accounts
         * Mist/Geth accounts.
@@ -50,7 +53,7 @@ Here are the possible ways to store ether:
 
 * **Can a contract pay for its execution?** No this is not possible. The gas for the execution must be provided by the address submitting the execution request.
 
-* **Can a contract call another contract?** Yes, this is possible, read `this <https://dappsforbeginners.wordpress.com/tutorials/interactions-between-contracts/>`_.
+* **Can a contract call another contract?** Yes, this is possible, read `about interactions between contracts <https://dappsforbeginners.wordpress.com/tutorials/interactions-between-contracts/>`_.
 
 * **Can a transaction be signed offline and then submitted on another online device?** Yes, you can refer to the solution from `Icebox <https://github.com/ConsenSys/icebox>`_.
 

source/introduction/glossary.rst

@@ -87,7 +87,7 @@ Glossary
       Epoch is the interval between each regeneration of the DAG used as seed by the PoW algorithm Ethash. The epoch in specified as 30000 blocks.
 
    elliptic curve (cryptography)
-      Refers to an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields. See `here <https://en.wikipedia.org/wiki/Elliptic_curve_cryptography>`_.
+      Refers to an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields. See `elliptic curve cryptography <https://en.wikipedia.org/wiki/Elliptic_curve_cryptography>`_.
 
    wallet
       A wallet, in the most generic sense, refers to anything that can store ether or any other crypto token. In the crypto space in general, the term wallet is used to mean anything from a single private/public key pair (like a single paper wallet) all the way to applications that manage multiple key pairs, like the Mist Ethereum wallet.
@@ -200,6 +200,7 @@ Glossary
 
    morden
       Morden is the first Ethereum alternative testnet. It is expected to continue throughout the Frontier and Homestead era.
+
    testnet
       A mirror network of the production Ethereum network that is meant for testing. See Morden.
 
@@ -243,7 +244,7 @@ Glossary
       The number of hash calculations made per second.
 
    serialization
-      The process of converting a data structure into a sequence of bytes. Ethereum internally uses an encoding format called recursive-length prefix encoding (RLP), described `here <https://github.com/ethereum/wiki/wiki/RLP>`_.
+      The process of converting a data structure into a sequence of bytes. Ethereum internally uses an encoding format called recursive-length prefix encoding (RLP), described in the `RLP section of the wiki <https://github.com/ethereum/wiki/wiki/RLP>`_.
 
    double spend
       A deliberate blockchain fork, where a user with a large amount of mining power sends a transaction to purchase some produce, then after receiving the product creates another transaction sending the same coins to themselves. The attacker then creates a block, at the same level as the block containing the original transaction but containing the second transaction instead, and starts mining on the fork. If the attacker has more than 50% of all mining power, the double spend is guaranteed to succeed eventually at any block depth. Below 50%, there is some probability of success, but it is usually only substantial at a depth up to about 2-5; for this reason, most cryptocurrency exchanges, gambling sites and financial services wait until six blocks have been produced ("six confirmations") before accepting a payment.
@@ -349,7 +350,6 @@ Glossary
       A computer program that runs as a background process instead of in direct control by an interactive user.
 
    system service
-
    base layer service
       Services such as SWARM and Whisper which are built into the Ethereum platform.
 

source/introduction/the-homestead-release.rst

@@ -24,7 +24,7 @@ Homestead  hard fork changes
 Ethereum in the narrow formal sense is a suite of ptotocols.
 Homestead comes with a few backward-incompatible protocol changes, and therefore will require a hard fork.
 
-* `EIP 2: <https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki>
+* `EIP 2: <https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki>`_
 
   * cost for creating contracts via a transaction is increased from 21000 to 53000. Contract creation from a contract using the ``CREATE`` opcode is unaffected.
   * transaction signatures whose s-value is greater than ``secp256k1n/2`` are now considered invalid

source/using-ethereum-the-basics/ether.rst

@@ -52,9 +52,8 @@ Ether can also be transfered using the **geth console**.
     > eth.sendTransaction({from:sender, to:receiver, value: amount})
 
 
-For more information of Ether transfer transactions, see _`Account Types, Gas, and Transactions`.
-
-Ethereum is unique in the realm of cryptocurrencies in that ether has utility value as a cryptofuel, commonly referred to as "gas". Beyond transaction fees, gas is a central part of every network request and requires the sender to pay for the computing resources consumed. The gas cost is dynamically calculated, based on the volume and complexity of the request and multiplied by the current gas price. Its value as a cryptofuel has the effect of increasing the stability and long-term  demand for ether and Ethereum as a whole. For more information, see _`Account Types, Gas, and Transactions`
+For more information of Ether transfer transactions, see :ref:`account-types-gas-and-transactions`.
 
+Ethereum is unique in the realm of cryptocurrencies in that ether has utility value as a cryptofuel, commonly referred to as "gas". Beyond transaction fees, gas is a central part of every network request and requires the sender to pay for the computing resources consumed. The gas cost is dynamically calculated, based on the volume and complexity of the request and multiplied by the current gas price. Its value as a cryptofuel has the effect of increasing the stability and long-term  demand for ether and Ethereum as a whole. For more information, see :ref:`account-types-gas-and-transactions`.