WIP: reorganizing docs

aleaf · Oct 2, 2024 · 3e131bc · 3e131bc
1 parent 7b77dbf
commit 3e131bc
Show file tree

Hide file tree

Showing 6 changed files with 27 additions and 17 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -45,8 +45,14 @@
     'numpydoc',
     'nbsphinx',
     'sphinx_copybutton',
+    'sphinx_gallery.gen_gallery'
 ]
 
+sphinx_gallery_conf = {
+     'examples_dirs': 'examples',   # path to your example scripts
+     'gallery_dirs': 'gallery',  # path to where to save gallery generated output
+}
+
 # Configuration options for plot_directive. See:
 # https://github.com/matplotlib/matplotlib/blob/f3ed922d935751e08494e5fb5311d3050a3b637b/lib/matplotlib/sphinxext/plot_directive.py#L81
 plot_html_show_source_link = False
@@ -94,7 +100,8 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'examples/*.rst']
+exclude_patterns = ['_build', #'examples/*.rst'
+                    ]
 
 
 # The name of the Pygments (syntax highlighting) style to use.

diff --git a/docs/source/examples/meras.rst b/docs/source/examples/meras.rst
@@ -1,6 +1,8 @@
+MERAS 3: Creating an SFR package from a configuration file with custom hydrography
+-------------------------------------------------------------------------------------
 This example illustrates the use of custom hydrography with the configuration file, as well the scalability of SFRmaker. An SFR package is generated on a regular 1 km grid (Clark and others, 2018) that spans the Mississippi Embayment, a former bay of the Gulf of Mexico that includes portions of Missouri, Tennessee, Arkansas, Mississippi and Louisiana. The goal is to update the stream network for the Mississippi Embayment Regional Aquifer System (MERAS 2) model (Haugh and others, 2020; Clark and others, 2013) to include a realistic representation of the thousands of mapped streams (Figure 1). NHDPlus hydrography were preprocessed to only include the lines intersecting the MERAS footprint that had a total upstream drainage (arbolate sum) of 20 kilometers or greater (figure 1). Attribute information from NHDPlus, including routing connections, elevations at the upstream and downstream ends of line arcs and channel widths estimated from arbolate sum values (e.g. ref: Feinstein and others (2010, p 266)) were joined to the culled flowlines, which were then saved to a shapefile.
 
-.. figure:: examples/meras_comparison.png
+.. figure:: meras_comparison.png
     :align: left
     :scale: 70 %
     :alt: alternate text
@@ -14,7 +16,7 @@ The configuration file for the Mississippi Embayment example is shown below. The
 
 meras_sfrmaker_config.yml:
 ##############################
-.. literalinclude:: ../../examples/meras/meras_sfrmaker_config.yml
+.. literalinclude:: ../../../examples/meras/meras_sfrmaker_config.yml
     :language: yaml
     :linenos:
 
@@ -32,13 +34,13 @@ The above configuration file can be used to generate an SFR package with the fol
 
 make_sfr.py:
 ##############################
-.. literalinclude:: ../../examples/meras/make_sfr.py
+.. literalinclude:: ../../../examples/meras/make_sfr.py
     :language: python
     :linenos:
 
 This will produce an sfr package for MODFLOW-6, csv table representations of the SFR input, and shapefiles for visualizing the SFR package. The resulting SFR package is shown in Figure 2.
 
-.. figure:: examples/meras_results.png
+.. figure:: meras_results.png
     :align: left
     :scale: 100 %
     :alt: alternate text

diff --git a/docs/source/examples/tf.rst b/docs/source/examples/tf.rst
@@ -1,24 +1,26 @@
+The Tyler Forks watershed: Creating an SFR package from a configuration file using NHDPlus
+--------------------------------------------------------------------------------------------------
 This example shows how a configuration file can be used to build an SFR package from NHDPlus data, with a model grid specified using a MODFLOW model or a shapefile. The example is set in the Tyler Forks watershed in northern Wisconsin, where groundwater/surface interactions are the primary modeling interest.
 
 In the first configuration file, the Name file and workspace for a MODFLOW-NWT model are specified. An active area denoting where the SFR package will be built is provided with a shapefile. NHDPlus data are provided as a file path to the root folder level for a drainage basin (for example, 04, The Great Lakes), assuming the files within that path are in the same structure as the `download from the NHDPlus website <https://nhdplus.com/NHDPlus/NHDPlusV2_data.php>`_. Finally, a dem is provided as a `a more accurate source of streambed elevations <notebooks/Streambed_elevation_demo.html>`_.
 
 tf_sfrmaker_config.yml:
 ##############################
-.. literalinclude:: ../../examples/tylerforks/tf_sfrmaker_config.yml
+.. literalinclude:: ../../../examples/tylerforks/tf_sfrmaker_config.yml
     :language: yaml
     :linenos:
 
 In the second configuration file, no model is specified, so a package version, name, output path and length units are specified. The model grid is specified from a shapefile that has attribute fields indicating the row, column location of each cell. NHPlus data a specified as individual files.
 
-.. literalinclude:: ../../examples/tylerforks/tf_sfrmaker_config2.yml
+.. literalinclude:: ../../../examples/tylerforks/tf_sfrmaker_config2.yml
     :language: yaml
     :linenos:
 
 Either of these configuration files can then be used with a python script similar to the following:
 
 tylerforks/make_sfr.py:
 ##############################
-.. literalinclude:: ../../examples/tylerforks/make_sfr.py
+.. literalinclude:: ../../../examples/tylerforks/make_sfr.py
     :language: python
     :linenos:
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -27,15 +27,14 @@ version |version|
    :caption: Getting Started
 
     Philosophy <philosophy>
-    Examples <examples>
+    Examples <examples/index.rst>
     Installation <installation>
 
 .. toctree::
   :maxdepth: 2
   :caption: User Guide
 
    Input Requirements <inputs>
-   Using SFRmaker with a configuration file <examples>
    Basic Usage in a scripting context <notebooks/SFRmaker_demo>
    Preprocessing NHDPlus version 2 data <notebooks/preprocessing_demo>
    Using SFRmaker with NHDPlus High Resolution <notebooks/lines_from_NHDPlusHR_demo>

diff --git a/docs/source/inputs.rst b/docs/source/inputs.rst
@@ -45,7 +45,7 @@ Any Polyline shapefile can be supplied in lieu of NHDPlus, but it must have the
 
 2) Model grid information
 --------------------------
-is supplied by creating a 	```flopy.discretization.Grid`` instance`_, instance or `via a shapefile`_, as shown in the :doc:`examples <examples>`.
+is supplied by creating a 	```flopy.discretization.Grid`` instance`_, instance or `via a shapefile`_, as shown in the :doc:`examples <examples/index>`.
 
 .. _flopy.discretization.Grid`` instance`: https://aleaf.github.io/sfrmaker/usage.html#create-a-flopy-structuredgrid-instance-defining-the-model-grid
 

diff --git a/docs/source/examples.rst → using_w_config_file.rst b/docs/source/examples.rst → using_w_config_file.rst
@@ -3,10 +3,10 @@ Using SFRmaker with a configuration file
 ========================================
 For many applications, the easiest way to get started with SFRmaker is to create a configuration file that can then be used in a simple script to generate an SFR package. The two example problems below illustrate the use of SFRmaker with a configuration file. A :ref:`comprehensive summary of configuration file inputs <SFRmaker configuration file options>` is provided in the reference section.
 
-MERAS 3: Creating an SFR package from a configuration file with custom hydrography
--------------------------------------------------------------------------------------
-.. include:: examples/meras.rst
 
-The Tyler Forks watershed: Creating an SFR package from a configuration file using NHDPlus
---------------------------------------------------------------------------------------------------
-.. include:: examples/tf.rst
+.. toctree::
+   :maxdepth: 1
+   :caption: Configuration file workflow examples
+
+   MERAS 3 <meras>
+   Tyler Forks <tf>