Minor docs update

CONTRIBUTING.rst

@@ -34,15 +34,51 @@ by adding missing information and correcting mistakes.
 ``laue-dials`` documentation uses Sphinx_ as its main documentation compiler.
 This means that the docs are kept in the same repository as the project code, and
 that any documentation update is done in the same way was a code contribution.
-When working on documentation changes in your local machine, you can
-compile them using ``tox``
+When working on documentation changes in your local machine, make sure you have installed the "docs" extension of the package::
 
-    tox -e docs
+    pip install laue-dials[docs]
+
+or if, more likely, you've cloned the repo and are installing from your local copy::
+
+    pip install -e ".[docs]"
+
+This makes sure that in addition to ``laue-dials``, you've also installed Sphinx and all of the necessary Sphinx extensions to build the docs.
+
+To build a copy of the docs locally, you can navigate into the ``docs/`` subdirectory and call::
+
+    make clean
+    make html
+
+The ``docs/_build/html/`` directory should now contain ``.html`` files which can be opened in your web browser.
+
+Adding docs for new command-line functions
+------------------------------------------
+
+In order for a command-line function to be added to the documention, you must do two things:
+
+1. Create a file in the ``docs/cli/`` directory called ``{function-name}.rst``. The contents of this file should match the contents of the other ``.rst`` files in this directory, using the new function's name as appropriate. The easiest thing is to just copy one of the existing files and update it. Note that if the ``====`` header underneath ``laue_dials.{function-name}`` isn't the same length as the text, Sphinx might get mad.
+2. Add the new function to the table of contents in ``docs/cli/functions.md``. Otherwise, your new page will exist, but there will be no link to it anywhere!
+
+In order for a new command-line function to be maximally compatible with this documentation format, three things should be true:
+
+1. The function's ``help_message`` should exist and contain a useful introduction to the function and it's usage.
+2. The function's most commonly used parameters should have expert level 0.
+3. Any parameters of the function that ever need to be available to the user should have expert level no higher than 2.
+
+Adding other pages to the docs
+------------------------------
+
+New pages can be added to the docs by creating new files in the `docs/` directory. Files can be either ``.rst`` (reStructuredText) or ``.md`` (Markdown) formats. Additionally, ``.md`` files can contain chunks of reStructuredText wrapped inside of ``{eval-rst}`` triple braces::
+
+    ## Markdown heading
+    Lots of *markdown* code.
+
+    ```{eval-rst}
+    .. rstcommand::
 
-and use Python's built-in web server for a preview in your web browser
-(``http://localhost:8000``)::
+    ```
 
-    python3 -m http.server --directory 'docs/_build/html'
+Additionally, you must add any new pages to the table of contents listed in ``docs/index.rst``. List your new page as ``Display Name <filename>``, and place it where you'd like it to appear in order in the Table of Contents.
 
 
 Code Contributions

docs/index.rst

@@ -7,11 +7,12 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   Command-Line Reference <cli/functions>
+   Tutorial <tutorial>
    Contributions & Help <contributing>
    License <license>
    Authors <authors>
    Changelog <changelog>
-   Command-Line Reference <cli/functions>
    Full API Reference <api/modules>
 
 

docs/tutorial.md

@@ -0,0 +1,3 @@
+# Tutorial
+
+Coming soon! This page will contain a walkthrough of how you might use `laue-dials` on your favorite polychromatic crystallography dataset.