From 3e131bcd0b3fc24aef034a579a1567b3fa8fcf02 Mon Sep 17 00:00:00 2001 From: "Leaf, Andrew T" Date: Thu, 21 Sep 2023 10:11:37 -0500 Subject: [PATCH] WIP: reorganizing docs --- docs/source/conf.py | 9 ++++++++- docs/source/examples/meras.rst | 10 ++++++---- docs/source/examples/tf.rst | 8 +++++--- docs/source/index.rst | 3 +-- docs/source/inputs.rst | 2 +- docs/source/examples.rst => using_w_config_file.rst | 12 ++++++------ 6 files changed, 27 insertions(+), 17 deletions(-) rename docs/source/examples.rst => using_w_config_file.rst (55%) diff --git a/docs/source/conf.py b/docs/source/conf.py index cd143556..fa8b036c 100644 --- 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 index 1d18267c..93bc4198 100644 --- 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 index 78052742..a7be99b6 100644 --- a/docs/source/examples/tf.rst +++ b/docs/source/examples/tf.rst @@ -1,16 +1,18 @@ +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 `_. Finally, a dem is provided as a `a more accurate source of streambed elevations `_. 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: @@ -18,7 +20,7 @@ Either of these configuration files can then be used with a python script simila 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 index ce095d31..14f614a2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,7 +27,7 @@ version |version| :caption: Getting Started Philosophy - Examples + Examples Installation .. toctree:: @@ -35,7 +35,6 @@ version |version| :caption: User Guide Input Requirements - Using SFRmaker with a configuration file Basic Usage in a scripting context Preprocessing NHDPlus version 2 data Using SFRmaker with NHDPlus High Resolution diff --git a/docs/source/inputs.rst b/docs/source/inputs.rst index f63a78de..e0888a96 100644 --- 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 `. +is supplied by creating a ```flopy.discretization.Grid`` instance`_, instance or `via a shapefile`_, as shown in the :doc:`examples `. .. _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 b/using_w_config_file.rst similarity index 55% rename from docs/source/examples.rst rename to using_w_config_file.rst index 6f351886..a5d0db54 100644 --- a/docs/source/examples.rst +++ b/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 ` 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 + Tyler Forks