Merge pull request #202 from stsievert/v0.6.0-dev-docs

DOC: improve dev environment documentation

docs/source/devs/env.rst

@@ -12,8 +12,9 @@ in a development container.
 
 .. attention::
 
-    The ``dr`` script bind-mounts your local copy of the repository into the container.
-    Any edits you make outside the container will be reflected inside (and vice versa).
+    The ``dr`` script bind-mounts your local copy of the repository into the
+    container.  Any edits you make outside the container will be reflected
+    inside (and vice versa).
 
 Anything you pass to ``dr`` will be executed inside the container.
 The initial working directory is the ``htmap`` repository inside the container.
@@ -25,8 +26,20 @@ Running the Test Suite
 ----------------------
 
 The fastest way to run the test suite is to run ``pytest`` inside the
-development container with multiple workers.
-``pytest -n 4`` seems to be a good number for laptops.
+development container with multiple workers:
+
+.. code:: shell
+
+   $ ./dr bash  # for example
+   # ...
+   mapper@161b6af91d72:~/htmap$ pytest
+
+``pytest -n 4`` seems to be a good number for laptops:
+
+.. code:: shell
+
+   mapper@161b6af91d72:~/htmap$ pytest -n 4
+
 See `pytest-xdist <https://pypi.org/project/pytest-xdist/>`_ for more details.
 
 
@@ -36,8 +49,16 @@ Building the Docs
 HTMap's documentation is served by `Read the Docs <https://readthedocs.org/>`_,
 which builds the docs as well.
 However, it can be helpful to build the docs locally during development.
-From inside the development container, run `docs/autobuild.sh` inside the
-development container.
+From inside the development container,
+
+.. code:: shell
+
+   $ ./dr bash
+   # ...
+   mapper@161b6af91d72:~/htmap$ ./docs/autobuild
+   NOTE: CONNECT TO http://127.0.0.1:8000 NOT WHAT SPHINX-AUTOBUILD TELLS YOU
+   # trimmed; visit URL above
+
 Note the startup message: ignore the link that `sphinx-autobuild` gives you,
 and instead go to http://127.0.0.1:8000 to see the built documentation.
 
@@ -50,7 +71,12 @@ The tutorials are run inside a specialized Docker container
 (not the development container).
 To test whether the Binder container is working properly, run the
 ``binder/test.sh`` script from the repository root
-(i.e., not from inside the development container).
+(i.e., not from inside the development container):
+
+.. code:: shell
+
+   $ ./binder/test.sh
+
 It will give you a link to enter into your web browser that will land you in the
 same Jupyter environment you would get on Binder.
 The ``binder/edit.sh`` will do the same, but also bind-mount the tutorials into

dr

@@ -4,6 +4,6 @@ CONTAINER_TAG='htmap-dev'
 
 set -e
 
-docker build --quiet -t ${CONTAINER_TAG} --file docker/Dockerfile .
+docker build -t ${CONTAINER_TAG} --file docker/Dockerfile .
 
 docker run -it --rm --mount type=bind,src="$PWD",dst=/home/mapper/htmap -p 8000:8000 ${CONTAINER_TAG} $@