Merge pull request #595 from nmearl/update-docs

Update docs
spacetelescope · Nov 30, 2018 · f1c74b8 · f1c74b8
2 parents a7f0351 + 02ac29e
commit f1c74b8
Show file tree

Hide file tree

Showing 24 changed files with 177,328 additions and 85,191 deletions.
diff --git a/.rtd-environment.yml b/.rtd-environment.yml
@@ -11,3 +11,4 @@ dependencies:
     - numpy
     - pip:
         - sphinx-astropy
+        - sphinx-rtd-theme
diff --git a/.travis.yml b/.travis.yml
@@ -42,7 +42,7 @@ env:
 
         # List other runtime dependencies for the package that are available as
         # pip packages here.
-        - PIP_DEPENDENCIES='pyqt5 pyqtgraph qtawesome qtpy click git+https://github.com/astropy/specutils sphinx-astropy pytest-astropy pytest-qt'
+        - PIP_DEPENDENCIES='pyqt5 pyqtgraph qtawesome qtpy click specutils>=0.5.1 sphinx-astropy sphinx-rtd-theme pytest-astropy pytest-qt'
 
         # Conda packages for affiliated packages are hosted in channel
         # "astropy" while builds for astropy LTS with recent numpy versions

diff --git a/docs/_static/disabled_data_item.png b/docs/_static/disabled_data_item.png
diff --git a/docs/_static/loader_select.png b/docs/_static/loader_select.png
diff --git a/docs/_static/logo_icon.png b/docs/_static/logo_icon.png
diff --git a/docs/_static/open_file_dialog.png b/docs/_static/open_file_dialog.png
diff --git a/docs/_static/spec_icon.png b/docs/_static/spec_icon.png
diff --git a/docs/_static/specviz_horizontal.png b/docs/_static/specviz_horizontal.png
diff --git a/docs/_static/title_horizontal.png b/docs/_static/title_horizontal.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -104,23 +104,23 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes. To override the custom theme, set this to the
 # name of a builtin theme or the name of a custom theme in html_theme_path.
-#html_theme = None
+html_theme = "sphinx_rtd_theme"
 
 
 # Please update these texts to match the name of your package.
-html_theme_options = {
-    'logotext1': 'spec',  # white,  semi-bold
-    'logotext2': 'viz',  # orange, light
-    'logotext3': ':docs'   # white,  light
-    }
+# html_theme_options = {
+#     'logotext1': 'spec',  # white,  semi-bold
+#     'logotext2': 'viz',  # orange, light
+#     'logotext3': ':docs'   # white,  light
+#     }
 
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = '_static/specviz_logo.png'
+html_logo = '_static/logo_icon.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

diff --git a/docs/getting-started.rst b/docs/getting-started.rst
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -0,0 +1,90 @@
+.. _specviz-start:
+
+Getting Started
+===============
+
+Loading a Basic Spectrum
+------------------------
+
+Lets start by loading a simple, known spectrum. If you followed the steps in
+:ref:`specviz-launching`, you should see the specviz window up, but without a
+spectrum.
+
+There are two options to load a spectrum data file:
+
+1. Load the spectrum with a pre-defined data loader, or a custom user-defined data loader.
+2. Utilize the :doc:`Loader Wizard </loader_wizard>` to create a new custom loader, and use that to load your data.
+
+Either way, the specific loader for your data can be selected from the drop
+down list in the open file dialog
+
+.. image:: _static/open_file_dialog.png
+
+.. image:: _static/loader_select.png
+
+Once the file has been loaded, you will be greeted with a plotted spectrum.
+
+
+Exporting Spectra
+-----------------
+
+A user can export a given spectrum in the data list by highlighting the
+spectrum and clicking the ``Export Data`` button in the main toolbar. This
+will provide the user with a save file dialog where they may choose where to
+save the exported spectrum file.
+
+.. note::
+
+    `ECSV <http://docs.astropy.org/en/stable/api/astropy.io.ascii.Ecsv.html>`_
+    is currently the only supported export format. This will change in the
+    future as more exporting formats are supported in the specutils package.
+
+
+Workspaces and Plots
+--------------------
+
+Loaded data is added to the global data list for the entire workspace. A
+workspace is an instance of the SpecViz application. Several can be
+open at once and more can be added by selecting ``File > New Workspace`` from
+the menu bar. Workspaces are completely independent of one another, and the
+user can have as many workspaces are they wish.
+
+Plots are the visual representation of a selection of data items within a
+particular workspace. A user can have as many plots as they wish, and new plots
+can be created by clicking the ``New Plot`` button in the main toolbar.
+Likewise, plot windows can be removed by clicking the ``X`` button in the plot
+tab.
+
+Plots all share the same data list within a workspace. The caveat is that plots
+can only show data that have equivalent units. Any data that cannot be added
+to a plot will show as disabled in the data list.
+
+.. image:: _static/disabled_data_item.png
+
+Clicking the checkbox next to an item in the data list will plot the data
+item on the current plot.
+
+
+Using Regions
+-------------
+
+Interesting regions can be defined by adding an ROI to the plot. This is done
+via the ``Add Region`` button in the plot toolbar. Multiple regions can be
+used when defining e.g. areas the user might wish to use for model fitting.
+
+A blue highlighted region is considered the _active_ region, and will in cases
+where it is imported (e.g. statistics), will be used to define the region
+used in the calculations.
+
+.. note::
+
+    Currently, only one region can be the "selected" region. This will change
+    in the future to allow a subset of plotted region to be defined as
+    "selected".
+
+Removing a region is accomplished by clicking the ``Remove Region`` button.
+Only the currently selected region is removed.
+
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,10 +1,35 @@
-Specviz
-=======
+.. image:: _static/title_horizontal.png
 
-This is the documentation for specviz, a qt-based interactive GUI for
-visualizing astronomical spectra.  It is written in the Python programming
-language, and therefore leverages the `specutils` package, and can be run
-anywhere Python is supported (See .
+|
+
+Introduction
+============
+
+SpecViz is a tool for visualization and quick-look analysis of 1D astronomical
+spectra. It is written in the Python programming language, and therefore can be
+run anywhere Python is supported (see :ref:`specviz-installation`). SpecViz is
+built on top of the `SpecUtils <https://specutils.rtfd.io>`_ Astropy-affiliated
+python library, providing a visual, interactive interface to the analysis
+capabilities in that library.
+
+SpecViz allows spectra to be easily plotted and examined. It supports
+flexible spectral units conversions, custom plotting attributes, interactive
+selections, multiple plots, and other features.
+
+SpecViz notably includes a measurement tool for spectral lines which
+enables the user, with a few mouse actions, to perform and record measurements.
+It has a model fitting capability that enables the user to create simple
+(e.g., single Gaussian) or multi-component models (e.g., multiple Gaussians for
+emission and absorption lines in addition to regions of flat continuua).
+A typical data-analysis workflow might involve data exploration using SpecViz
+and then scripting to create more complex measurements or modeling workflows
+using SpecUtils.
+
+SpecViz will soon include the ability to:
+
+- Measure the average of multiple spectra, detrending, and apply Fourier filters.
+- Interactively renormalize data from spectral templates.
+- And more...
 
 
 Installation and Setup
@@ -23,9 +48,9 @@ Using SpecViz
 .. toctree::
    :maxdepth: 2
 
-   getting-started
+   getting_started
    unit_conversion
    arithmetic-layer
    loader_wizard
    model_fitting
-   stats_sidebar
+   statistics
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,6 +1,6 @@
 .. highlight:: console
 
-.. _specviz_installation:
+.. _specviz-installation:
 
 Installation
 ============

diff --git a/docs/launching.rst b/docs/launching.rst
@@ -5,17 +5,31 @@
 Launching SpecViz
 =================
 
-Once you've installed SpecViz, you can launch it via the command line::
+Once the user has installed SpecViz, they can launch it via the command line::
 
     $ specviz
 
 
-If you only wish to inspect a single file, you can also pass in the filename
-as a command line argument, as follows::
+If the user wishes to inspect a single file, they can also pass in the filename
+as a command line argument along with the ``-F`` flag as follows::
 
-    $ specviz filename
+    $ specviz -F <filename>
 
+.. code-block::bash
 
-You may also include the name of a custom loader as second optional argument::
+    $ specviz -F ~/Downloads/COS_FUV.fits
 
-    $ specviz filename --format="my-custom-format"
+
+In the above case, the loader registry functionality will attempt to select
+the best available loader for the data. If the user wishes to specify a
+specific loader for their data, a ``-L`` flag can be passed with the loader
+name
+
+    $ specviz -F <filename> -L <loader_name>
+
+.. code-block::bash
+
+    $ specviz -F ~/Downloads/COS_FUV.fits -L HST/COS
+
+To get further help with the command line options, simply type
+``specviz --help``.
diff --git a/docs/stats_sidebar.rst → docs/statistics.rst b/docs/stats_sidebar.rst → docs/statistics.rst
@@ -1,7 +1,7 @@
 .. _specviz-stats_sidebar:
 
-Right Sidebar Statistics Display
---------------------------------
+Spectrum Statistics
+-------------------
 
 11 statistic/analysis functions are calculated using the input spectrum
 or  specified region of interest, depending on what is selected in the

diff --git a/setup.cfg b/setup.cfg
@@ -49,7 +49,7 @@ edit_on_github = True
 github_project = spacetelescope/specviz
 # install_requires should be formatted as a comma-separated list, e.g.:
 # install_requires = astropy, scipy, matplotlib
-install_requires = astropy>=3.0, pyqt5, pyqtgraph, qtawesome, qtpy, specutils>=0.4, click, pytest, asteval
+install_requires = astropy>=3.0, pyqt5, pyqtgraph, qtawesome, qtpy, specutils>=0.5.1, click, pytest, asteval
 # version should be PEP386 compatible (http://www.python.org/dev/peps/pep-0386)
 version = 0.6.dev0
 # Note: you will also need to change this in your package's __init__.py

diff --git a/specviz/app.py b/specviz/app.py
@@ -31,7 +31,7 @@ def __init__(self, *args, file_path=None, file_loader=None, embedded=False,
         super(Application, self).__init__(*args, **kwargs)
 
         # Set application icon
-        self.setWindowIcon(QIcon(":/icons/icon.png"))
+        self.setWindowIcon(QIcon(":/icons/specviz.icns"))
 
         # Load local plugins
         self.load_local_plugins()

diff --git a/specviz/data/resources/icon.ico b/specviz/data/resources/icon.ico
diff --git a/specviz/data/resources/icon.png b/specviz/data/resources/icon.png
diff --git a/specviz/data/resources/resources.qrc b/specviz/data/resources/resources.qrc
@@ -1,5 +1,6 @@
 <RCC>
   <qresource prefix="/icons">
+    <file>specviz.icns</file>
     <file>configuration.svg</file>
     <file>title.png</file>
     <file>005-stats.svg</file>
@@ -27,6 +28,5 @@
     <file>region_remove.svg</file>
     <file>selection.svg</file>
     <file>house.svg</file>
-    <file>icon.ico</file>
   </qresource>
 </RCC>
diff --git a/specviz/data/resources/title.png b/specviz/data/resources/title.png
diff --git a/specviz/plugins/loader_wizard/loader_wizard.ui b/specviz/plugins/loader_wizard/loader_wizard.ui
@@ -135,7 +135,7 @@
    <item>
     <layout class="QHBoxLayout" name="horizontalLayout_4">
      <item>
-      <layout class="QGridLayout" name="gridLayout" rowstretch="0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0">
+      <layout class="QGridLayout" name="gridLayout" rowstretch="0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0">
        <item row="6" column="0">
         <widget class="QLabel" name="label_data_units">
          <property name="text">
@@ -594,7 +594,7 @@
            <number>0</number>
           </property>
           <item>
-           <layout class="QVBoxLayout" name="layout_preview" stretch=""/>
+           <layout class="QVBoxLayout" name="layout_preview"/>
           </item>
          </layout>
         </widget>
@@ -742,6 +742,8 @@
    </item>
   </layout>
  </widget>
- <resources/>
+ <resources>
+  <include location="../../data/resources/resources.qrc"/>
+ </resources>
  <connections/>
 </ui>