Refactored the docs on dev/test node setup

docs/server/source/appendices/rethinkdb-backup.md

@@ -22,8 +22,6 @@ That's just one possible way of setting up the file system so as to provide extr
 
 Another way to get similar reliability would be to mount the RethinkDB data directory on an [Amazon EBS](https://aws.amazon.com/ebs/) volume. Each Amazon EBS volume is, "automatically replicated within its Availability Zone to protect you from component failure, offering high availability and durability."
 
-See [the section on setting up storage for RethinkDB](../dev-and-test/setup-run-node.html#set-up-storage-for-rethinkdb-data) for more details.
-
 As with shard replication, live file-system replication protects against many failure modes, but it doesn't protect against them all. You should still consider having normal, "cold" backups.
 
 
@@ -108,7 +106,7 @@ Considerations for BigchainDB:
 
 Although it's not advertised as such, RethinkDB's built-in replication feature is similar to continous backup, except the "backup" (i.e. the set of replica shards) is spread across all the nodes. One could take that idea a bit farther by creating a set of backup-only servers with one full backup:
 
-* Give all the original BigchainDB nodes (RethinkDB nodes) the server tag `original`. This is the default if you used the RethinkDB config file suggested in the section titled [Configure RethinkDB Server](../dev-and-test/setup-run-node.html#configure-rethinkdb-server).
+* Give all the original BigchainDB nodes (RethinkDB nodes) the server tag `original`.
 * Set up a group of servers running RethinkDB only, and give them the server tag `backup`. The `backup` servers could be geographically separated from all the `original` nodes (or not; it's up to the consortium to decide).
 * Clients shouldn't be able to read from or write to servers in the `backup` set.
 * Send a RethinkDB reconfigure command to the RethinkDB cluster to make it so that the `original` set has the same number of replicas as before (or maybe one less), and the `backup` set has one replica. Also, make sure the `primary_replica_tag='original'` so that all primary shards live on the `original` nodes.

docs/server/source/appendices/run-with-ansible.md

@@ -60,7 +60,14 @@ Verify BigchainDB Docker:
 $ docker ps | grep bigchaindb
 ```
 
-The playbook also installs the BigchainDB python driver, so can instantly make transactions and verify the functionality. The `bdb_root_url` can be be one of the following:
+The playbook also installs the BigchainDB Python Driver, 
+so you can use it to make transactions
+and verify the functionality of your BigchainDB node.
+See the [BigchainDB Python Driver documentation](https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html)
+for details on how to use it.
+
+
+Note 1: The `bdb_root_url` can be be one of the following:
 ```text
 # BigchainDB is running as a process
 bdb_root_url = http://<HOST-IP>:9984
@@ -70,4 +77,5 @@ OR
 # BigchainDB is running inside a docker container
 bdb_root_url = http://<HOST-IP>:<DOCKER-PUBLISHED-PORT>
 ```
-For more details on `how to make a transaction?` Please refer to [Basic Usage Examples](https://docs.bigchaindb.com/projects/py-driver/en/latest/connect.html).
+
+Note 2: BigchainDB has [other drivers as well](../drivers-clients/index.html).

docs/server/source/appendices/run-with-vagrant.md

@@ -122,7 +122,13 @@ Verify BigchainDB Docker:
 $ docker ps | grep bigchaindb
 ```
 
-BigchainDB python driver is pre-installed in the instance, so you can instantly make transactions and verify the functionality. The `bdb_root_url` can be one of the following:
+The BigchainDB Python Driver is pre-installed in the instance,
+so you can use it to make transactions
+and verify the functionality of your BigchainDB node.
+See the [BigchainDB Python Driver documentation](https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html)
+for details on how to use it.
+
+Note 1: The `bdb_root_url` can be one of the following:
 ```text
 # BigchainDB is running as a process
 bdb_root_url = http://<HOST-IP>:9984
@@ -132,6 +138,5 @@ OR
 # BigchainDB is running inside a docker container
 bdb_root_url = http://<HOST-IP>:<DOCKER-PUBLISHED-HOST-PORT>
 ```
-For more details on *how to make a transaction?* Please refer to [Basic Usage Examples](https://docs.bigchaindb.com/projects/py-driver/en/latest/connect.html).
 
-*Note*: If you want to make transactions remotely, you need to install the `bigchaindb-driver`. For detailed instructions on how to install the driver and make your first transaction. Please refer to [Quickstart/Installation](https://docs.bigchaindb.com/projects/py-driver/en/latest/quickstart.html) of BigchainDB driver.
+Note 2: BigchainDB has [other drivers as well](../drivers-clients/index.html).

docs/server/source/dev-and-test/index.rst

@@ -1,12 +1,13 @@
 Develop & Test BigchainDB Server
 ================================
 
+This section outlines some ways that you could set up a minimal BigchainDB node for development and testing purposes. For additional guidance on how you could help develop BigchainDB, see the `CONTRIBUTING.md file on GitHub <https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md>`_.
+
 .. toctree::
    :maxdepth: 1
 
-   setup-run-node
-   setup-bdb-host
-   setup-bdb-docker
-   ../appendices/run-with-vagrant
-   ../appendices/run-with-ansible
+   Using a Local Dev Machine <setup-bdb-host>
+   Using a Local Dev Machine and Docker <setup-bdb-docker>
+   Using Vagrant <../appendices/run-with-vagrant>
+   Using Ansible <../appendices/run-with-ansible>
    running-all-tests

docs/server/source/dev-and-test/setup-bdb-host.md

@@ -1,7 +1,12 @@
 # Set Up BigchainDB Node on Local Dev Machine
 
+The BigchainDB core dev team develops BigchainDB on recent Ubuntu, Fedora and CentOS distributions, so we recommend you use one of those. BigchainDB Server doesn't work on Windows or macOS (unless you use a VM or containers).
+
+
 ## With MongoDB
 
+First read the BigchainDB [CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md). It outlines the steps to set up a machine for developing and testing BigchainDB.
+
 Create a default BigchainDB config file (in `$HOME/.bigchaindb`):
 ```text
 $ bigchaindb -y configure mongodb
@@ -25,11 +30,13 @@ To run BigchainDB Server, do:
 $ bigchaindb start
 ```
 
-You can [run all the unit tests](running-unit-tests.html) to test your installation.
+You can [run all the unit tests](running-all-tests.html) to test your installation.
+
 
-The BigchainDB [CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md) has more details about how to contribute.
 ## With RethinkDB
 
+First read the BigchainDB [CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md). It outlines the steps to set up a machine for developing and testing BigchainDB.
+
 Create a default BigchainDB config file (in `$HOME/.bigchaindb`):
 ```text
 $ bigchaindb -y configure rethinkdb
@@ -52,5 +59,3 @@ $ bigchaindb start
 ```
 
 You can [run all the unit tests](running-all-tests.html) to test your installation.
-
-The BigchainDB [CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md) has more details about how to contribute.

docs/server/source/introduction.md

@@ -16,7 +16,7 @@ Note that there are a few kinds of nodes:
 ## Setup Instructions for Various Cases
 
 * [Quickstart](quickstart.html)
-* [Set up a local BigchainDB node for development, experimenting and testing](dev-and-test/setup-run-node.html)
+* [Set up a local BigchainDB node for development, experimenting and testing](dev-and-test/index.html)
 * [Set up and run a BigchainDB cluster](clusters.html)
 
 There are some old RethinkDB-based deployment instructions as well: