Editing Sphinx docs, to create a more useful organization, add code examples, etc. Still in progress

Author: emiliom

docs/source/contribute.rst

@@ -1,11 +1,55 @@
-Contribute to Documentation
+Contributing
 ============================
 
+You can help with ODM2 Python API by contributing code, helping with the documentation, and engaging the team via GitHub issues (questions, solutions, etc).
+
+
+Installing the development version from the development branch on github
+----------------------------------
+
+Note: We follow the `Gitflow workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`__ for development.
+
+1. Download both ``requirements.txt`` and ``requirements-dev.txt``.
+   
+   .. code-block:: bash
+   
+       wget https://raw.githubusercontent.com/ODM2/ODM2PythonAPI/master/requirements.txt
+       wget https://raw.githubusercontent.com/ODM2/ODM2PythonAPI/master/requirements-dev.txt
+
+2. Create conda environment ``odm2api_dev`` from the two ``requirements*`` text files.
+
+   .. code-block:: bash
+  
+       conda create -n odm2api_dev -c conda-forge python=2.7 --file requirements.txt --file requirements-dev.txt
+
+3. Activate conda environment.
+   - MacOSX/Linux:
+   
+   .. code-block:: bash
+       
+       source activate odm2api_dev
+   
+   - Windows:
+   
+   .. code-block:: bash
+      
+       activate odm2api_dev
+    
+4. Install the latest commit from the development branch
+
+   .. code-block:: bash
+      
+       pip install git+https://github.com/ODM2/ODM2PythonAPI.git@development#egg=odm2api
+
+
+Contribute to Documentation
+----------------------------------
+
 This guide is a reference on how to contribute to ODM2 Documentation effort
 for the many `ODM2 Software Ecosystem <https://github.com/ODM2/odm2-software-ecosystem>`__.
 
 Conventions
------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are a few conventions that should be followed
 when writing docstrings within the code:
@@ -30,7 +74,7 @@ Please add any additional conventions that you think should be in place
 within `the github issue #106 <https://github.com/ODM2/ODM2PythonAPI/issues/106>`__.
 
 Pull requests
--------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once changes has been in place within your forked copy of the repository
 you are working on, please create a pull request to add your contribution

docs/source/installing.rst docs/source/getstarted.rstdocs/source/installing.rst renamed to docs/source/getstarted.rst

@@ -1,6 +1,13 @@
-Installation
+Get Started
 ============
 
+
+Install the latest release as a conda package from conda-forge
+----------------------------------------------
+
+conda
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The easiest and most reliable way to install the ODM2 Python API
 (``odm2api``) is using the `Conda package management
 system <https://conda.io/docs/>`__ via either
@@ -21,8 +28,8 @@ To activate a conda environment, say, "myenv":
 changes have been made to support Python 3.x, but they haven't been
 tested thoroughly.
 
-Latest release, from conda-forge anaconda.org channel
-----------------------------------------------
+Install the conda package
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The `latest release <https://github.com/ODM2/ODM2PythonAPI/releases>`_ is available
 on the `conda-forge anaconda.org channel <https://anaconda.org/conda-forge/odm2api>`_
@@ -43,39 +50,16 @@ To create a new environment "myenv" with the ``odm2api`` package:
     conda create -n myenv -c conda-forge python=2.7 odm2api
 
 
-Installing the development version from the ``development`` branch on github
-----------------------------------
-
-Note: We follow the `Gitflow workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`__ for development.
-
-1. Download both ``requirements.txt`` and ``requirements-dev.txt``.
-   
-   .. code-block:: bash
-   
-       wget https://raw.githubusercontent.com/ODM2/ODM2PythonAPI/master/requirements.txt
-       wget https://raw.githubusercontent.com/ODM2/ODM2PythonAPI/master/requirements-dev.txt
-
-2. Create conda environment ``odm2api_dev`` from the two ``requirements*`` text files.
-
-   .. code-block:: bash
-  
-       conda create -n odm2api_dev -c conda-forge python=2.7 --file requirements.txt --file requirements-dev.txt
-
-3. Activate conda environment.
-   - MacOSX/Linux:
-   
-   .. code-block:: bash
-       
-       source activate odm2api_dev
-   
-   - Windows:
-   
-   .. code-block:: bash
-      
-       activate odm2api_dev
-    
-4. Install the latest commit from the development branch
-
-   .. code-block:: bash
-      
-       pip install git+https://github.com/ODM2/ODM2PythonAPI.git@development#egg=odm2api
+Code examples
+----------------------------------------------
+
+
+
+
+Sample Jupyter notebooks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Also mention the associated SQLite ODM2 databases. And the conda environment file.
+
+https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/WaterQualityMeasurements_RetrieveVisualize.ipynb
+https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/TimeSeries_RetrieveVisualize.ipynb

docs/source/index.rst

@@ -7,11 +7,11 @@ A Python-based application programmer's interface for the `Observations Data Mod
    :maxdepth: 2
    :caption: Contents:
 
-   installing
+   getstarted
    modules
    odm2models
-   credits
    contribute
+   credits
 
 Indices and tables
 ==================