Merge pull request #567 from ethereum/doc

Doc first draft

docs/analysis_tab.rst

@@ -0,0 +1,27 @@
+Analysis
+========
+
+This section gives information about the last compilation.
+A new analysis is by default run at each compilation.
+
+It gives detailed information about the contract code and is a good way to avoid code mistakes and enforce best practices.
+
+.. image:: images/remix_analysistab.png
+
+Here the list of analyzers:
+
+    - Security:
+        - Transaction origin: Warn if tx.origin is used
+        - Check effects: Avoid potential reentrancy bugs
+        - Inline assembly: Use of Inline Assembly
+        - Block timestamp: Semantics maybe unclear
+        - Low level calls: Semantics maybe unclear
+        - Block.blockhash usage: Semantics maybe unclear
+
+    - Gas & Economy:
+        - Gas costs: Warn if the gas requirements of functions are too high
+        - This on local calls: Invocation of local functions via this
+
+    - Miscellaneous:
+        - Constant functions: Check for potentially constant functions
+        - Similar variable names: Check if variable names are too similar

docs/compile_tab.rst

@@ -0,0 +1,20 @@
+Compiling contracts
+===================
+
+By default Remix triggers a compilation each time the current file is changed or another file is selected.
+If the contract has a lot of dependencies and takes a long time to compile, it is possible to disable the `autocompilation`.
+
+.. image:: images/remix_compiletab.png
+
+After each compilation, a list is updated with all the newly compiled contracts.
+
+`Details` modal dialog displays detailed information about the current selected contract.
+
+From this tab, you can also publish your contract to Swarm (only non abstract contract can be published).
+
+Published data contains notably the ``abi`` and solidity source code.
+
+After a contract is published, you can find its metadata information using the `bzz` URL located in the details modal dialog ``SWARM LOCATION``.
+
+Compilation Errors and Warning are displayed below the contract section. At each compilation, the static analysis tab builds a report. It is very valuable to address reported issues even if the compiler doesn't complain.
+(see :doc:`../analysis_tab`)

docs/debugger_tab.rst

@@ -0,0 +1,11 @@
+Debugging
+=========
+
+This module allows you to debug the transaction.
+It can be used to deploy transactions created from Remix and already mined transactions.
+(debugging works only if the current environment provides needed features).
+
+.. image:: images/remix_debuggertab.png
+
+All informations about debugging are describing in the following link:
+:doc:`../tutorial_debug`

docs/file_explorer.rst

@@ -0,0 +1,37 @@
+File Explorer
+=============
+
+The file explorer lists by default all the files stored in your browser. You can see them in the `browser` folder. You can always rename, remove or add new files to the file explorer.
+
+.. image:: images/remix_file_explorer_browser.png
+
+Note that clearing the browser storage will permanently delete all the solidity sources you wrote. To avoid this, you can use Remixd, which enables you to store and sync files in the browser with your local files (for more information see :doc:`../tutorial_remixd_filesystem`)
+
+.. image:: images/remix_file_explorer_menu.png
+
+From the left to the right:
+
+Create new File
+---------------
+
+Creates a new file in the `browser` explorer.
+
+Add Local File
+--------------
+
+Allows you to select files from the local file system and import them to the Remix browser storage.
+
+Publish to Gist
+---------------
+
+Publishes files from the browser storage to an anonymous public gist.
+
+Copy to another instance
+------------------------
+
+Enables you to copy files from the browser storage to another instance (URL) of Remix.
+
+Connect to Localhost
+--------------------
+
+Allows to use file located in your file system (see :doc:`../tutorial_remixd_filesystem`).

docs/index.rst

@@ -10,6 +10,44 @@ This page will host documentation and tutorial about features Remix provides.
 
 Please go to `solidity.readthedocs.io <http://solidity.readthedocs.io>`_ for any information regarding ``Solidity``
 
+Overview
+--------
+
+Remix provides an integrated development environment for smart contract development. 
+It focuses on development and deployment of Solidity written smart contract.
+
+Remix is a good solution if you intend to:
+
+ - Develop smart contract (remix integrates a solidity editor).
+ - Debug smart contract execution.
+ - Access the state and properties of already deployed smart contract.
+ - Debug already committed transaction.
+ - Analyze solidity code to reduce coding mistake and enforce best practices.
+ - Together with Mist (or any tool which inject web3), Remix can be used to test and debug Dapp (see :doc:`../tutorial_mist`)
+
+Developping smart contract requires a deep understanding of the associated Blockchain technology. 
+
+!! Don't use Remix against a production network unless you are completely sure what you are doing !!
+
+This documentation describes all the features remix provides.
+The GUI can be separated in 4 parts. Click on one the link to get more information.
+
+ - :doc:`../file_explorer`
+ - :doc:`../solidity_editor`
+ - :doc:`../terminal`
+ - :doc:`../tabs_panel`
+    - :doc:`../compile_tab`
+    - :doc:`../run_tab`
+    - :doc:`../settings_tab`
+    - :doc:`../debugger_tab`
+    - :doc:`../analysis_tab`
+    - :doc:`../support_tab`
+    
+Quick Start
+-----------
+
+(see :doc:`../quickstart_javascriptvm`)
+
 Tutorial
 --------
 

docs/quickstart_javascriptvm.rst

@@ -0,0 +1,83 @@
+Quick Start using the JavaScript VM
+===================================
+
+There are 3 type of environments Remix can be plugged to (see :doc:`../run_tab`)
+both ``Web3 provider`` and ``Injected provider`` requires the use of an external tool.
+
+An Ethereum node for ``Web3 provider`` and Mist or Metamask for ``Injected provider``.
+
+The ``JavaScript VM`` mode is convenient because every execution run in your browser.
+Thus reloading the page will restart Remix with en empty state. it might also be better to use an external node for better performances.
+
+Selecting the VM mode
+---------------------
+
+Make sure the VM mode is selected. All accounts displayed in ``Accounts`` should have 100 ether.
+
+Sample contract
+---------------
+
+.. code-block:: none
+    
+    pragma solidity ^0.4.16;
+    contract testContract {
+        
+        uint value;
+        function testContract(uint _p) {
+            value = _p;
+        }
+        
+        function setP(uint _n) payable {
+            value = _n;
+        }
+        
+        function setNP(uint _n) {
+            value = _n;
+        }
+        
+        function get () constant returns (uint) {
+            return value;
+        }
+    }
+    
+That contract is very very basic, the goal is to quiclky start to create and to interact with.
+
+Deploying an instance
+---------------------
+
+The ``Compile tab`` displays informations related to the current contract (note that there can be more than one) (see :doc:`../compile_tab`).
+
+Switching now to ``Run tab`` allows to deploy an instance of the contract in the ``JavaScript VM`` state.
+
+.. image:: images/remix_quickstart_javascriptvm_creation.png
+
+The constructor of ``testContract`` needs a parameter (of type ``uint``). give any value and click on ``Create``.
+
+The transaction which deploy the instance of ``testContract`` is created.
+
+That could take several seconds in a "normal" blockchain (time for the transaction to be mined), in our the case execution is immediate (JavaScript VM).
+ 
+Looking at the terminal will inform you about the transaction. You can see details and start debugging it.
+
+The newly created instance is displayed in the ``run tab``.
+
+.. image:: images/remix_quickstart_javascriptvm_creationTransaction.png
+
+Interacting with an instance
+----------------------------
+
+This new instance contains 3 actions which corresponds to the 3 functions (``setP``, ``setPN``, ``get``).
+Clicking on ``SetP`` or ``SetPN`` will create a new transaction. 
+
+Note that ``SetP`` is ``payable`` (red action) : it is possible to send value (Ether) to the contract.
+
+``SetPN`` is not payable (light red action) : it is not possible to send value (Ether) to the contract.
+
+Clicking on ``get`` will not execute a transaction (blue action). It is not necessary to do so because ``get`` does not modify the state (variable ``value``) of this instance.
+
+As ``get`` is ``constant`` you can see the return value just below the action.
+
+.. image:: images/remix_quickstart_javascriptvm_callinginstance.png
+
+   
+   

docs/run_tab.rst

@@ -0,0 +1,55 @@
+Running transactions
+====================
+
+This tab is an important section of Remix. It allows you to send transactions to the current environment.
+
+.. image:: images/remix_runtab.png
+
+Run Setup
+---------
+
+These are the settings that enables you to directly influence the transaction execution:
+
+ - Environment:
+    - ``JavaScript VM``: All the transactions will be executed in a sandbox blockchain in the browser. That means nothing will be persisted and a page reload will restart a new blockchain from scratch, the old one will not be saved.
+
+    - ``Injected Provider``: Remix will connect to an injected web3 provider. ``Mist`` and ``Metamask`` are example of providers that inject web3, thus can be used with this option.
+
+    - ``Web3 Provider``: Remix will connect to a remote node. You will need to provide the URL address to the selected provider: geth, parity or any Ethereum client.
+
+ - Account: list of accounts associated with the current environment (and their associated balances)
+ - Gas Limit: maximum amount of gas that can be set for all the transactions created in Remix
+ - Value: amount of value for the next created transaction (this value is always reset to 0 after each transaction execution)
+
+ .. image:: images/remix_runtab_example.png
+
+Initiate Instance
+-----------------
+
+This section contains the list of compiled contracts and 2 actions:
+
+- ``At Address`` assumes the given address is an instance of the selected contract. It is then possible to interact with an already deployed contract. There's no check at this point so be careful when using this feature and be sure you trust the contract at that address.
+
+- ``Create`` send a transaction that deploy the selected contract. When the transaction is mined the newly created instance will be added (this might take several seconds). (note that if the ``constructor`` has parameters you need to specify them).
+
+Pending Instances
+-----------------
+
+Validating a transaction take several seconds. During this time the GUI shows it in a pending mode. When transaction is mined the number of pending transactions is updated
+and the transaction is added to the log (see :doc:`../terminal`)
+
+Instances List
+--------------
+
+This section contains list of instances to interact with.
+
+Several cases apply:
+ - The called function is declared as ``constant`` or ``pure`` in Solidity. The action has a blue background, clicking on it does not create a new transaction. (this is not necessary because there is not state changes) but will update the return value of the function.
+
+ - The called function has no special keywords. The action has a light red background, clicking on does create a new transaction. But this transaction cannot accept any amount of Ether.
+
+ - The called function is declared as ``payable`` in Solidity. The action has a red background, clicking on it does create a new transaction and this transaction can accept value.
+
+For more information about Solidity modifier, see `Solidity modifier <http://solidity.readthedocs.io/en/develop/miscellaneous.html?highlight=pure#modifiers>`_ .
+
+If a function requires input parameters, it is required to specify them.

docs/settings_tab.rst

@@ -0,0 +1,13 @@
+Settings
+========
+
+This section displays the current compiler version and allows to change to another version.
+
+.. image:: images/remix_settingstab.png
+
+Settings, available here:
+
+ - Text wrap: defines if the text in the editor should be wrapped.
+ - Enable optimization: defines if the compiler should enable optimization during compilation. Enabling this option saves execution gas.
+ It is useful to enable optimization for contracts ready to be deployed in production
+ but could lead to some inconsistency when debugging such a contract.

docs/solidity_editor.rst

@@ -0,0 +1,13 @@
+Solidity Editor
+===============
+
+Remix editor triggers a compilation each time the current file is changed or another file is selected. It also provides syntax highlighting mapped to solidity keywords.
+
+.. image:: images/remix_editor.png
+
+Here's the list of some important features:
+
+- It display opened files as tabs.
+- Compilation Warning and Error are displayed in the gutter
+- Remix saves the current file continuously (5s after the last changes)
+- +/- on the top left corner enable you to increase/decrease the font size of the editor

docs/support_tab.rst

@@ -0,0 +1,6 @@
+Support
+=======
+
+This section provides a link to the Remix issues where users can report a bug or suggest a feature, other useful links and and it displays a `Remix developers' channel <http://gitter.im/ethereum/remix>`_
+
+.. image:: images/remix_supporttab.png

docs/tabs_panel.rst

@@ -0,0 +1,9 @@
+Tabs Panel
+==========
+
+- :doc:`../compile_tab`
+- :doc:`../run_tab`
+- :doc:`../settings_tab`
+- :doc:`../debugger_tab`
+- :doc:`../analysis_tab`
+- :doc:`../support_tab`

docs/terminal.rst

@@ -0,0 +1,14 @@
+Terminal
+========
+
+.. image:: images/remix_terminal.png
+
+Features, available in the terminal:
+
+- It integrates a JavaScript interpreter and the ``web3`` object. It enables the execution of the JavaScript script which interacts with the current context. (note that ``web3`` is only available if the ``web provider`` or ``injected provider`` mode is selected).
+
+- It displays important actions made while interacting with the Remix IDE (i.e. sending a new transaction).
+
+- It displays transactions that are mined in the current context. You can choose to display all transactions or only transactions that refers to the contracts Remix knows (e.g transaction created from the Remix IDE).
+
+- It allows searching for the data and clearing the logs from the terminal.

docs/tutorial_debug.rst

@@ -71,8 +71,7 @@ Right panel / second tab from the left - fill in the ´´value´´ input (´1 et
 
 Then click on ``Donate``. As we are using the ``JavaScript VM``, everything goes almost instantly.
 
-Remix displays also some information related to each transaction result. On the right of each transaction result
+Remix displays also some information related to each transaction result. In the terminal, the transaction is logged and you can start debugging it.
-you can start debugging the corresponding transaction.
 
 .. image:: remix_startdebugging.png