doc: write section on developing with a conda env

.readthedocs.yml

@@ -2,4 +2,4 @@ python:
   version: 3
   pip_install: false
 conda:
-  file: conda/artiq-doc.yml
+  file: conda/artiq-doc.yaml

doc/manual/developing.rst

@@ -1,12 +1,44 @@
+Developing ARTIQ
+^^^^^^^^^^^^^^^^
+
+We describe two different approaches to creating a development environment for ARTIQ.
+
+The first method uses existing pre-compiled Anaconda packages for the development environment.
+This is fast and convenient because it avoids compiling the entire toolchain but developing individual components within the toolchain requires extra care.
+It is completely sufficient to develop and tweak the ARTIQ code and to build
+bitstreams.
+Some ARTIQ developers as well as the buildbot employs this method for continuous integration to build the ``artiq`` Anaconda packages and the bitstreams.
+
+The second method builds most components in the toolchain from their sources.
+This takes time and and care to reproduce precisely but it gives absolute control over the components and an immediate handle at developing them.
+Some ARTIQ developers use this method.
+It is only recommended for developers and advanced users.
+
+.. _develop-from-conda:
+
+ARTIQ Anaconda development environment
+======================================
+
+    1. Install ``git`` as recommended for your operating system and distribution.
+    2. Obtain ARTIQ::
+           $ git clone --recursive https://github.com/m-labs/artiq ~/artiq-dev/artiq
+           $ cd ~/artiq-dev/artiq
+    3. :ref:`Install Anaconda or Miniconda <install-anaconda>`
+    4. Create and activate a conda environment named ``artiq-dev`` and install the ``artiq-dev`` package which pulls in all the packages required to develop ARTIQ::
+           $ conda env create -f conda/artiq-dev.yaml
+           $ source activate artiq-dev
+    5. Add the ARTIQ source tree to the environment's search path::
+           $ python setup.py develop
+    6. :ref:`Install Xilinx ISE or Vivado <install-xilinx>`
+    7. :ref:`Obtain and install the JTAG SPI flash proxy bitstream <install-bscan-spi>`
+    8. :ref:`Configure OpenOCD <setup-openocd>`
+    9. :ref:`Build target binaries <build-target-binaries>`
+
 .. _install-from-source:
 
 Installing ARTIQ from source
 ============================
 
-.. note::
-	This method is only recommended for developers and advanced users. An easier way to install ARTIQ is via the Anaconda packages (see :ref:`Installing ARTIQ <install-from-conda>`).
-
-
 Preparing the build environment for the core device
 ---------------------------------------------------
 
@@ -88,6 +120,8 @@ Preparing the core device FPGA board
 
 These steps are required to generate gateware bitstream (``.bit``) files, build the MiSoC BIOS and ARTIQ runtime, and flash FPGA boards. If the board is already flashed, you may skip those steps and go directly to `Installing the host-side software`.
 
+.. _install-xilinx:
+
 * Install the FPGA vendor tools (i.e. Xilinx ISE and/or Vivado):
 
     * Get Xilinx tools from http://www.xilinx.com/support/download/index.htm. ISE can build gateware bitstreams both for boards using the Spartan-6 (Pipistrello) and 7-series devices (KC705), while Vivado supports only boards using 7-series devices.
@@ -106,6 +140,8 @@ These steps are required to generate gateware bitstream (``.bit``) files, build
 .. note::
     The options ``develop`` and ``--user`` are for setup.py to install Migen in ``~/.local/lib/python3.5``.
 
+.. _install-bscan-spi:
+
 * Install the required flash proxy gateware bitstreams:
 
     The purpose of the flash proxy gateware bitstream is to give programming software fast JTAG access to the flash connected to the FPGA.
@@ -164,6 +200,7 @@ These steps are required to generate gateware bitstream (``.bit``) files, build
 
     .. note:: Make sure that ``/usr/local/llvm-or1k/bin`` is first in your ``PATH``, so that the ``clang`` command you just built is found instead of the system one, if any.
 
+.. _build-target-binaries:
     * For Pipistrello::
 
         $ python3 -m artiq.gateware.targets.pipistrello

doc/manual/index.rst

@@ -8,7 +8,7 @@ Contents:
 
     introduction
     installing
-    installing_from_source
+    developing
     release_notes
     rtio
     getting_started_core

doc/manual/installing.rst

@@ -16,6 +16,7 @@ The conda package contains pre-built binaries that you can directly flash to you
     Conda packages are supported for Linux (64-bit) and Windows (32- and 64-bit).
     Users of other operating systems (32-bit Linux, BSD, OSX ...) should and can :ref:`install from source <install-from-source>`.
 
+.. _install-anaconda:
 
 Installing Anaconda or Miniconda
 --------------------------------
@@ -104,10 +105,13 @@ They are all shipped in the conda packages, along with the required flash proxy
 Installing OpenOCD
 ^^^^^^^^^^^^^^^^^^
 
-OpenOCD can be used to write the binary images into the core device FPGA board's flash memory. It can be installed using conda on both Linux and Windows::
+OpenOCD can be used to write the binary images into the core device FPGA board's flash memory.
+The ``artiq`` or ``artiq-dev`` conda packages install ``openocd`` automatically but it can also be installed explicitly using conda on both Linux and Windows::
 
     $ conda install openocd
 
+.. _setup-openocd:
+
 Some additional steps are necessary to ensure that OpenOCD can communicate with the FPGA board.
 
 On Linux, first ensure that the current user belongs to the ``plugdev`` group. If it does not, run ``sudo adduser $USER plugdev`` and relogin. Afterwards::
@@ -127,6 +131,11 @@ On Windows, a third-party tool, `Zadig <http://zadig.akeo.ie/>`_, is necessary.
 
 You may need to repeat these steps every time you plug the FPGA board into a port where it has not been plugged into previously on the same system.
 
+.. _flashing-core-device:
+
+Flashing the core device
+^^^^^^^^^^^^^^^^^^^^^^^^
+
 Then, you can flash the board:
 
 * For the Pipistrello board::