Add dev setup docs

doc/Makefile

@@ -66,9 +66,9 @@ generate-rst-from-md:
 	# generate contributing docs
 	mkdir -p source/dev
 	pandoc --from=markdown --to=rst --output=source/dev/_index.rst ../CONTRIBUTING.md
-	echo ".. _devindex:" > source/dev/index.rst
-	cat source/dev/_index.rst >> source/dev/index.rst
-	rm source/dev/_index.rst
+	echo ".. _contributing:" > source/dev/_contributing.rst
+	cat source/dev/_contributing.rst >> source/dev/contributing.rst
+	rm source/dev/_contributing.rst
 	# generate changelog
 	pandoc --from=markdown --to=rst --output=source/_changelog.rst ../CHANGELOG.md
 	echo ".. _changelog:" > source/changelog.rst

doc/source/dev/setup.rst

@@ -0,0 +1,35 @@
+.. _devinstall:
+
+********************************
+Developer setup and installation
+********************************
+
+When developing jobflow-remote, one does not necessarily need to set up 
+a remote runner environment and database.
+Instead, one can use the containerized setup provided as part of the integration
+tests.
+This requires a `Docker engine <https://docs.docker.com/engine/install/>`_ to be running on your local machine,
+as it will create and launch containers running MongoDB and Slurm to test job submission.
+
+These tests do not run by default (i.e., when simply running ``pytest``) as they conflict with the 
+units tests, but can instead be installed and then invoked with:
+
+.. code:: bash
+   pip install .[tests]
+   CI=1 pytest tests/integration
+
+When adding new features to jobflow-remote, please consider adding an
+integration test to ensure that the feature works as expected, before
+following the contributing instructions at :ref:`contributing`.
+
+.. warning::
+   The integration tests will create a container running MongoDB and Slurm
+   on your local machine that will be cleaned up when the tests finish.
+   If you ``KeyboardInterrupt`` the tests, the container may not be cleaned 
+   successfully.
+   A random free port will be chosen for Slurm and MongoDB each; if you
+   encounter errors with these ports (as the process can be system-dependent),
+   please raise an issue detailing your setup.
+   In this case, you may wish to manually override the pytest fixtures for 
+   port specification in ``tests/integration/conftest.py`` (but do not commit
+   these changes).