Update docs (#981)

doc_source/conf.py

@@ -52,7 +52,7 @@
     "deflist",
 ]
 
-autoapi_dirs = ["../gmprocess"]
+autoapi_dirs = ["../src/gmprocess"]
 autoapi_add_toctree_entry = False
 
 # Add any paths that contain templates here, relative to this directory.

doc_source/contents/developer/build_docs.md

@@ -1,28 +1,17 @@
----
-jupytext:
-  text_representation:
-    extension: .md
-    format_name: myst
-    format_version: '0.8'
-    jupytext_version: '1.4.1'
-kernelspec:
-  display_name: Python 3
-  language: python
-  name: python3
----
 # Build Documentation
 
-Some additional packages are required to build the documentation:
+Some additional packages are required to build the documentation, which can be included
+with the `doc` install option, e.g.,
 
 ```
-cd doc_source
-mamba install --file requirements.txt
+$ pip install .[doc]
 ```
 
 Then the docs are built with
 
 ```
-./makedocs.sh
+$ cd doc_source/
+$ ./makedocs.sh
 ```
 
 The docs can then be previewed by opening `../docs/index.html` in a browser.

doc_source/contents/getting-started/install.md

@@ -0,0 +1,101 @@
+# Installation
+
+Note that we used to use conda to manage dependencies but that was creating some
+difficulties and so we are now relying on pip as much as possible. 
+
+```{caution}
+There is an old gmprocess package available via conda. Please do not install this!
+It is very out of date and won't work.
+```
+
+However, we do recommend installing gmprocess into a virtual environment to isolate
+your code from other projects that might create conflicts and 
+[conda](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
+is good option for accomplishing this.
+
+We hope to be able to provide pip installs via pypi wheels soon.
+
+## Installing from source (Mac and Linux)
+
+```{admonition} Prerequisites
+- A C compiler. On a mac, this usually means installing XCode/Comomand Line tools. 
+  For linux, it depends on the type of linux but is usually very stright forward.
+- Bash shell, curl, and git.
+```
+
+First clone this repository and go into the root directory with
+
+```
+$ git clone https://github.com/usgs/groundmotion-processing.git
+$ cd groundmotion-processing
+```
+
+Now install with pip:
+
+```
+$ pip install .
+```
+
+Note that this will install the minimum requirements to run the code. There are 
+additional optional packages that can be installed that support running the unit tests 
+(`test`), code development (`dev`), and building the documentation (`doc`). To install
+these, you need to add the relevant option in brackets:
+
+```
+$ pip install .[test,dev,doc]
+```
+
+For development, it is also conveninet to install the code in "editable" mode by adding
+the `-e` option:
+
+```
+$ pip install -e .[test,dev,doc]
+```
+
+## Installing from source (Windows)
+
+Our development team is not proficient with Windows systems, so our ability to 
+support Windows installs is limited. But we know that the code compiles and 
+passes tests in Windows on our continuous integration systems. We have also 
+helped users install the code using the following steps.
+
+```{admonition} Prerequisites
+- A C compiler. We have had success follwing 
+  [these instructions](https://github.com/cython/cython/wiki/CythonExtensionsOnWindows#using-windows-sdk-cc-compiler-works-for-all-python-versions)
+  from cython.
+- Git and some kind of console.
+```
+
+First clone this repository and go into the root directory with
+
+```
+$ git clone https://github.com/usgs/groundmotion-processing.git
+$ cd groundmotion-processing
+```
+
+There is one depenency ([fiona](https://pypi.org/project/Fiona/)) that we have not been
+able to install with pip on Windows systems. So we rely on conda for this.
+
+Then install the ``gmprocess`` virtual environment and all of the dependencies
+and activate the environment
+
+```
+$ conda create --name gmprocess python=3.8 pip fiona 
+$ call activate gmprocess
+$ pip install -e .
+```
+
+## Tests
+
+If you included the optional `test` dependencies in the install step, then you can run
+the unit tests  in the root directory of this repositry:
+
+```
+$ py.test .
+```
+
+This will be followed by a lot of terminal output. Warnings are expected to occur and 
+do not indicate a problem. Errors indicate that something has gone wrong and you will 
+want to troubleshoot. You can create an issue in github if you are not able to resolve
+the problem.
+

doc_source/contents/manual/example.xml

@@ -3,7 +3,7 @@
   <Source>Taiwan Strong Motion Instrumentation Program via Central Weather Bureau</Source>
   <Module>ObsPy 1.3.0</Module>
   <ModuleURI>https://www.obspy.org</ModuleURI>
-  <Created>2022-07-27T00:00:44.935271Z</Created>
+  <Created>2022-08-15T22:05:22.168756Z</Created>
   <Network code="TW">
     <Description>source</Description>
     <Station code="EAS">

doc_source/contents/tutorials/response_spectra.md

@@ -20,7 +20,6 @@ There are a lot of imports to take care of first
 
 ```{code-cell} ipython3
 import os
-import pkg_resources
 
 import matplotlib.pyplot as plt
 from matplotlib import _cm as cm
@@ -36,6 +35,7 @@ from gmprocess.core.streamcollection import StreamCollection
 from gmprocess.utils.config import get_config
 from gmprocess.waveform_processing.processing import process_streams
 from gmprocess.utils.event import get_event_object
+from gmprocess.utils.constants import DATA_DIR
 from gmprocess.metrics.station_summary import StationSummary
 ```
 
@@ -46,8 +46,7 @@ and the event object for this earthquake
 ```{code-cell} ipython3
 :tags: [remove-stderr]
 # Path to example data
-datapath = os.path.join('data', 'testdata', 'demo', 'ci38457511', 'raw')
-datadir = pkg_resources.resource_filename('gmprocess', datapath)
+datadir = DATA_DIR / 'testdata' / 'demo' / 'ci38457511'/ 'raw'
 sc = StreamCollection.from_directory(datadir)
 sc.describe()
 ```
@@ -130,6 +129,7 @@ inputs.rake = 90.0
 inputs.hypo_depth = rotd_dict['ROTD(50.0)']['EarthquakeDepth']
 inputs.ztor = 0.0
 inputs.rjb = np.array([5.0])
+inputs.rrup = np.array([5.0])
 inputs.vs30 = np.array([760.0])
 inputs.sids = np.array([0])
 

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 649f1b60d4e8c6a16e30e6994a8ecbab
+config: fc8aa85e0041a65973ebe0b84db332c8
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_modules/gmprocess/apps/gmrecords.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../../genindex.html" /><link rel="search" title="Search" href="../../../search.html" />
 
     <meta name="generator" content="sphinx-5.1.1, furo 2022.06.21"/>
-        <title>gmprocess.apps.gmrecords - gmprocess 1.1.11.dev556+g618bb8b2.d20220727 documentation</title>
+        <title>gmprocess.apps.gmrecords - gmprocess 1.1.11.dev587+g1c7feaf6.d20220815 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?digest=40978830699223671f4072448e654b5958f38b89" />
     <link rel="stylesheet" type="text/css" href="../../../_static/graphviz.css" />
@@ -139,7 +139,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../../index.html"><div class="brand">gmprocess 1.1.11.dev556+g618bb8b2.d20220727 documentation</div></a>
+      <a href="../../../index.html"><div class="brand">gmprocess 1.1.11.dev587+g1c7feaf6.d20220815 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -221,6 +221,7 @@
 <li class="toctree-l4"><a class="reference internal" href="../../../autoapi/gmprocess/core/streamcollection/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.core.streamcollection</span></code></a></li>
 </ul>
 </li>
+<li class="toctree-l3"><a class="reference internal" href="../../../autoapi/gmprocess/data/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.data</span></code></a></li>
 <li class="toctree-l3 has-children"><a class="reference internal" href="../../../autoapi/gmprocess/io/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io</span></code></a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l4 has-children"><a class="reference internal" href="../../../autoapi/gmprocess/io/asdf/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.asdf</span></code></a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l5"><a class="reference internal" href="../../../autoapi/gmprocess/io/asdf/core/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.asdf.core</span></code></a></li>
@@ -287,7 +288,6 @@
 <li class="toctree-l5"><a class="reference internal" href="../../../autoapi/gmprocess/io/usc/core/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.usc.core</span></code></a></li>
 </ul>
 </li>
-<li class="toctree-l4"><a class="reference internal" href="../../../autoapi/gmprocess/io/catalog/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.catalog</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="../../../autoapi/gmprocess/io/fetcher/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.fetcher</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="../../../autoapi/gmprocess/io/global_fetcher/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.global_fetcher</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="../../../autoapi/gmprocess/io/nga/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.io.nga</span></code></a></li>
@@ -435,7 +435,6 @@
 <li class="toctree-l4"><a class="reference internal" href="../../../autoapi/gmprocess/waveform_processing/zero_crossings/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.waveform_processing.zero_crossings</span></code></a></li>
 </ul>
 </li>
-<li class="toctree-l3"><a class="reference internal" href="../../../autoapi/gmprocess/version/index.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">gmprocess.version</span></code></a></li>
 </ul>
 </li>
 </ul>
@@ -482,15 +481,16 @@ <h1>Source code for gmprocess.apps.gmrecords</h1><div class="highlight"><pre>
 <span class="kn">import</span> <span class="nn">copy</span>
 <span class="kn">import</span> <span class="nn">importlib</span>
 <span class="kn">import</span> <span class="nn">pkgutil</span>
-<span class="kn">import</span> <span class="nn">pkg_resources</span>
 <span class="kn">import</span> <span class="nn">inspect</span>
 <span class="kn">import</span> <span class="nn">argparse</span>
 <span class="kn">import</span> <span class="nn">logging</span>
 <span class="kn">import</span> <span class="nn">shutil</span>
+<span class="kn">import</span> <span class="nn">importlib.metadata</span>
 
-<span class="kn">from</span> <span class="nn">..</span> <span class="kn">import</span> <span class="n">__version__</span> <span class="k">as</span> <span class="n">VERSION</span>
 <span class="kn">from</span> <span class="nn">..subcommands.lazy_loader</span> <span class="kn">import</span> <span class="n">LazyLoader</span>
 
+<span class="n">VERSION</span> <span class="o">=</span> <span class="n">importlib</span><span class="o">.</span><span class="n">metadata</span><span class="o">.</span><span class="n">version</span><span class="p">(</span><span class="s2">&quot;gmprocess&quot;</span><span class="p">)</span>
+
 <span class="n">configobj</span> <span class="o">=</span> <span class="n">LazyLoader</span><span class="p">(</span><span class="s2">&quot;configobj&quot;</span><span class="p">,</span> <span class="nb">globals</span><span class="p">(),</span> <span class="s2">&quot;configobj&quot;</span><span class="p">)</span>
 <span class="n">setuptools_scm</span> <span class="o">=</span> <span class="n">LazyLoader</span><span class="p">(</span><span class="s2">&quot;setuptools_scm&quot;</span><span class="p">,</span> <span class="nb">globals</span><span class="p">(),</span> <span class="s2">&quot;setuptools_scm&quot;</span><span class="p">)</span>
 
@@ -666,12 +666,8 @@ <h1>Source code for gmprocess.apps.gmrecords</h1><div class="highlight"><pre>
 
         <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&quot;CALLED_FROM_PYTEST&quot;</span><span class="p">)</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">conf_path</span> <span class="o">=</span> <span class="n">const</span><span class="o">.</span><span class="n">CONFIG_PATH_TEST</span>  <span class="c1"># ~/gmptest</span>
-            <span class="c1"># Put test config in conf_path</span>
-            <span class="n">data_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span>
-                <span class="n">pkg_resources</span><span class="o">.</span><span class="n">resource_filename</span><span class="p">(</span><span class="s2">&quot;gmprocess&quot;</span><span class="p">,</span> <span class="s2">&quot;data&quot;</span><span class="p">)</span>
-            <span class="p">)</span>
             <span class="n">test_conf_file</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">normpath</span><span class="p">(</span>
-                <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">data_dir</span><span class="p">,</span> <span class="n">const</span><span class="o">.</span><span class="n">CONFIG_FILE_TEST</span><span class="p">)</span>  <span class="c1"># config_test.yml</span>
+                <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">const</span><span class="o">.</span><span class="n">DATA_DIR</span><span class="p">,</span> <span class="n">const</span><span class="o">.</span><span class="n">CONFIG_FILE_TEST</span><span class="p">)</span>  <span class="c1"># config_test.yml</span>
             <span class="p">)</span>
             <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">conf_path</span><span class="p">):</span>
                 <span class="n">os</span><span class="o">.</span><span class="n">mkdir</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">conf_path</span><span class="p">)</span>