Build the Documentation. (#17)

* Corrections of docstrings and some clean up.

* Add Differential import to main __init__.py

To solve this issue when building docs.

AttributeError: module 'spectrum_overload' has no attribute 'Differential'

* Update doc strings in classes.

* Add paths to module in doc conf.

* Change default theme.

* Update index.rst

* Add documentation about installation.

* Quickstart doc.

* Document available classes.

Using autodoc.

* Tidy spacing in docs.

* rearrange order of requirements.

* Add numpy to setup_requires.

To resolve issue with pyastronomy.

* Remove pyastronomy from requirements.txt

* Update requirements regarding pyastronomy.

* Edits to quickstart.

* Add docs extra_requirements to setup.py

* Run requirements.txt in setup.py.

* Add pyastronomy to travis.yml

So that tests will run before pyastronomy fixed.

* Adjust comment of setup.cfg - unimportant

* Fix setup.py error.

missing comma for docs: dependencies.

* Try empty install requires.

* Add readthedocs YAML config file.

* try pyastronomy in doc requirements.

* Add docs/.build to gitignore.

Ignores build files for docs.

* Add editable installation to docs.

* Note about classes not building.

And how to build manually.

* Re-add index and search to home page.

.gitignore

@@ -1,3 +1,5 @@
+docs/.build/
+
 #sync
 .sync/
 

.readthedocs.yml

@@ -0,0 +1,17 @@
+# Read the Docs Configuration File
+
+# Build PDF aswell as HTML and JSON
+formats:
+    - pdf
+
+# Requirements file
+requirements_file:
+    requirements.txt
+
+python:
+    version: 3.5
+    setup_py_install: true
+    # From extras_require in setup.py
+    extra_requirements:
+        - tests
+        - docs

.travis.yml

@@ -29,9 +29,9 @@ install:
   #- conda install --yes -c dan_blanchard python-coveralls nose-cov
   - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION numpy scipy astropy
   - source activate test-environment
+  - pip install pyastronomy
   - python setup.py install
 
-
   - pip install pytest-cov python-coveralls
   - pip install -r requirements.txt
 # install:

docs/classes.rst

@@ -0,0 +1,49 @@
+.. _classes
+
+=================
+Available Classes
+=================
+Currently there are two classes available.
+    - :ref:`Spectrum <spectrumclass>`
+    - :ref:`DifferentialSpectrum <diffclass>`
+
+
+.. _spectrumclass:
+
+.. note::
+    Unfortunately the auto-documentation for these classes does not build properly yet due to the ``Pyastronomy`` install dependency `issue. <https://github.com/sczesla/PyAstronomy/issues/22>`_
+    I hope to see it here soon.
+
+    If you need you can try and build this documentation yourself from the root `spectrum_overload` directory::
+
+        pip install -e .[docs]   # editable installation, install docs dependencies.
+        cd docs
+        make html
+
+    This page will be docs/.build/classes.html
+
+Spectrum
+=========
+
+A class to contain a spectrum. The operators have been overloaded so that you can easily manipulate spectra.
+
+.. autoclass:: spectrum_overload.Spectrum.Spectrum
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. _diffclass:
+
+Differential Spectrum
+=====================
+Compute the difference between two :ref:`Spectrum <spectrumclass>` objects.
+
+This is in an introductory state and need more work.
+
+Would be useful add an s-profile function from `Ferluga et al. 1997 <http://aas.aanda.org/articles/aas/ps/1997/01/dst6676.ps.gz>`_. The subtraction of two gaussian lines with a RV offset.
+
+.. autoclass:: spectrum_overload.Differential.DifferentialSpectrum
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -14,8 +14,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-# import sys
 import os
+import sys
 
 try:
     import sphinx_rtd_theme
@@ -29,6 +29,9 @@
 with open(os.path.join(base_dir, "spectrum_overload", "__about__.py")) as f:
     exec(f.read(), about)
 
+
+sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), ".."))
+sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), "..", "spectrum_overload"))
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -136,7 +139,8 @@
     html_theme = "sphinx_rtd_theme"
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 else:
-    html_theme = "default"
+    # html_theme = "default"
+    html_theme = "sphinxdoc"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/index.rst

@@ -1,31 +1,51 @@
 .. Spectrum documentation master file, created by
    sphinx-quickstart on Sun Sep 11 23:45:23 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+
+.. _home:
 
 =============================================
 Welcome to spectrum_overload's documentation!
 =============================================
 .. image:: https://travis-ci.org/jason-neal/spectrum_overload.svg?branch=develop
     :target: https://travis-ci.org/jason-neal/spectrum_overload
-    
+
 .. image:: https://coveralls.io/repos/github/jason-neal/spectrum_overload/badge.svg?branch=develop
     :target: https://coveralls.io/github/jason-neal/spectrum_overload?branch=develop
 
 
-spectrum_overload contains a spectrum class which contains overloaded operators.
-This means that you can easily divide and subtract spectra from each other.
-
-If the spectra are do not have the same wavelenght axis then it is automatially interpolated so that they are the same.
-
+Spectrum_overload is to manipulate astronomical spectra in a spectrum class with :ref:`overloaded operators <overloaded_operators>`.
+This means that you can easily divide and subtract spectra from each other using the math operators ``+``, ``-``, ``*``, ``/``, ``**`` keeping the wavelength, flux and headers together.
 
 .. toctree::
    :maxdepth: 2
 
+   installation
+   quickstart
+   classes
+
+
+Other Projects
+===============
+There are many other packages that deal with spectra, none that I know of overload the operators.
 
-quickstart
-installation
+In alphabetical order:
 
+    - `astropy/specutils <https://github.com/astropy/specutils>`_
+    - `cokelaer/spectrum <https://github.com/cokelaer/spectrum>`_
+    - `crawfordsm/specreduce <https://github.com/crawfordsm/specreduce>`_
+    - `pyspeckit/spectrum <https://github.com/pyspeckit/pyspeckit/tree/master/pyspeckit/spectrum>`_
+    - `PySpectrograph/Spectra <https://github.com/crawfordsm/pyspectrograph/tree/master/PySpectrograph/Spectra>`_
+
+I am sure there are others.
+
+
+Contributions
+=============
+Any contributions and/or suggestions to improve this module are very welcome.
+
+Submit `issues <https://github.com/jason-neal/spectrum_overload/issues>`_, suggestions or pull requests to `jason-neal/spectrum_overload <https://github.com/jason-neal/spectrum_overload>`_.
+
+This is my first attempt at creating classes, and packaging a python project so any *helpful* feedback is appreciated.
 
 
 Indices and tables
@@ -34,4 +54,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/installation.rst

@@ -0,0 +1,82 @@
+
+.. _install:
+
+=============================================
+Installation
+=============================================
+Spectrum_overload is currently available from ``github``.
+
+Navigate to where you want to put files.
+Then Download:
+
+with ``git``::
+
+    $ git clone https://github.com/jason-neal/spectrum_overload.git
+
+To install, run::
+
+    $ cd spectrum_overload
+    $ python setup.py install
+
+    # Or:
+
+    $ cd spectrum_overload
+    $ pip install .
+
+    # Or, for an editable installation:
+
+    $ cd spectrum_overload
+    $ pip install -e .
+
+The plan is to have it available via ``pypi`` someday in the future.::
+
+    # Bug me about this.
+    $ pip install spectrum-overload
+
+That day is not today...
+
+If you have any issues with installation of spectrum_overload please open an `issue`_ so it can be resolved.
+
+.. _issue:  https://github.com/jason-neal/spectrum_overload/issues
+
+
+Requirements
+============
+The main requirements are
+
+    - `numpy <https://www.numpy.org/>`_
+    - `astropy <https://www.astropy.org/>`_
+    - `scipy <https://www.scipy.org/>`_
+    - `pyastronomy <http://www.hs.uni-hamburg.de/DE/Ins/Per/Czesla/PyA/PyA/index.html>`_
+
+If you are needing to use this package you probably have these installed already...
+
+Unfortunately `pyastronomy <http://www.hs.uni-hamburg.de/DE/Ins/Per/Czesla/PyA/PyA/index.html>`_ cannot be added to the ``requirements.txt`` alongside ``numpy`` due to `issue #22 <https://github.com/sczesla/PyAstronomy/issues/22>`_ with the setup dependency of ``numpy`` in ``pyastronomy``.
+If you do not have it installed already then run::
+
+    $ pip install pyastronomy
+
+Other requirements are needed for running the `pytest <https://docs.pytest.org/en/latest/>`_ test suite.
+If you want to try run the tests, run::
+
+    $ python setup.py test
+
+after normal installation.
+
+These other dependencies that you may need are
+
+    - pytest-runner
+    - hypothesis
+    - pytest
+    - pytest-cov
+    - python-coveralls
+    - coverage
+
+
+Editable Installation
+=====================
+If you want to modify spectrum_overload you can instead install it like::
+
+    $ python setup.py develop
+
+..  or  pip install -e . when available

docs/quickstart.rst

@@ -0,0 +1,71 @@
+.. _quickstart:
+
+==================
+Quickstart Guide
+==================
+First install spectrum_overload via the :ref:`installation guide <install>`.
+
+Import the Spectrum class into your code.
+
+::
+
+    from spectrum_overload.Spectrum import Spectrum
+
+Then to create a spectrum object, and exponentially scale it by 2 use:
+
+::
+
+    s = Spectrum(flux=f, xaxis=x)
+
+    # exponential scaling
+    s = s ** 2
+
+where ``f`` and ``x`` are 1D lists or numpy arrays.
+
+.. note::
+
+	Flux is the first kwarg. Be careful not to switch the order of flux and xaxis when not specifying the kwarg names.
+
+By default the spectrum is "calibrated". If the xaxis is only the pixel values of your spectra you can pass
+
+::
+
+    s = Spectrum(flux=f, xaxis=pxls, calibrated=False)
+
+or if no xaxis is given it will be set by
+
+::
+
+    xaxis = np.arange(len(flux))
+
+You can calibrate the spectra with a polynomial using the ``calibrate_with`` method which uses ``np.polyval``::
+
+    s.calibrate_with([p0, p1, p2 ...])
+
+
+.. _overloaded_operators:
+
+Overloaded Operators
+====================
+The main purpose of this package is overloading the operators ``+``, ``-``, ``*``, ``/``, ``**`` to work with spectrum objects. e.g::
+
+    # Given two spectra
+    s1 = Spectrum(...)
+    s2 = Spectrum(...)
+
+    # You can easily do the following operations.
+    add = s1 + s2
+    subtract = s1 - s2
+    multiply = s1 * s2
+    divide = s1 / s2
+    power = s1 ** a  # where a is a number
+
+
+This is to make easier to do some basic manipulation of spectra, average spectra, take the difference, normalization,
+exponential scaling etc...
+
+.. note ::
+
+    Its probably best to interpolate the spectra to the same xaxis yourself before hand.
+    If the spectra do not have the same wavelength axis then it is automatically spline interpolated
+    to match the first spectrum or to another defined new xaxis.

requirements.txt

@@ -1,7 +1,7 @@
-pyastronomy
 numpy
 astropy
 scipy
+#pyastronomy
 hypothesis
 pytest
 pytest-cov

setup.cfg

@@ -1,9 +1,9 @@
 # setup.py configuration file?
 # http://doc.pytest.org/en/latest/goodpractices.html
-# Should now beable to call python setup.py test and test will run pytest
+# Should now be able to call python setup.py test and test will run pytest
 
 [aliases]
 test=pytest
 
 [tool:pytest]
-addopts = --verbose
+addopts = --verbose

setup.py

@@ -42,6 +42,10 @@
 with open(os.path.join(base_dir, "spectrum_overload", "__about__.py")) as f:
     exec(f.read(), about)
 
+# https://www.reddit.com/r/Python/comments/3uzl2a/setuppy_requirementstxt_or_a_combination/
+with open('requirements.txt') as f:
+    requirements = f.read().splitlines()
+
 setup(
     name='spectrum_overload',
 
@@ -107,17 +111,19 @@
     # your project is installed. For an analysis of "install_requires" vs pip's
     # requirements files see:
     # https://packaging.python.org/en/latest/requirements.html
-    install_requires=['numpy', 'hypothesis', 'astropy', 'scipy'],
+    # install_requires=requirements,
+    install_requires=[],
+    #install_requires=["numpy", "scipy", "astropy", "pyastronomy"],
     setup_requires=['pytest-runner'],
-    tests_require=['pytest'],
+    tests_require=['pytest', "hypothesis"],
     # List additional groups of dependencies here (e.g. development
     # dependencies). You can install these using the following syntax,
     # for example:
     # $ pip install -e .[dev,test]
     extras_require={
         'dev': ['check-manifest'],
-        'test': (['coverage', 'pytest', 'pytest-cov', 'python-coveralls',
-                 'hypothesis'],)
+        'test': ['coverage', 'pytest', 'pytest-cov', 'python-coveralls', 'hypothesis'],
+        'docs': ['sphinx >= 1.4', 'sphinx_rtd_theme', 'pyastronomy']
     },
 
     # If there are data files included in your packages that need to be