Merge pull request #39 from astrofrog/more-docs

Updates to documentation

aas_timeseries/views.py

@@ -13,7 +13,7 @@
 
 VALID_TIME_FORMATS = {}
 VALID_TIME_FORMATS['absolute'] = ['jd', 'mjd', 'unix', 'iso', 'auto']
-VALID_TIME_FORMATS['relative'] = ['seconds']
+VALID_TIME_FORMATS['relative'] = ['seconds', 'hours', 'days', 'years']
 VALID_TIME_FORMATS['phase'] = ['unity', 'degrees', 'radians']
 
 VALID_TIME_MODES = ['absolute', 'relative', 'phase']
@@ -67,7 +67,7 @@ def xlabel(self):
             if self._time_mode == 'absolute':
                 return 'Time'
             elif self._time_mode == 'relative':
-                return 'Relative Time (s)'
+                return 'Relative Time ({0})'.format(self.time_format[0])
             elif self._time_mode == 'phase':
                 return 'Phase'
 

docs/index.rst

@@ -4,19 +4,17 @@ Interactive time series figures in AAS journals
 About
 -----
 
-The **aas-timeseries** package is being developed as part of a project between
+The **aas-timeseries** package has been developed as part of a project between
 `AAS Publishing <https://journals.aas.org/>`_ and the `Astropy Project
 <http://www.astropy.org>`_. The goal of this project is to provide astronomers
 with all the tools needed to make it possible for astronomers to read in and
 manipulate time series in Astropy, produce interactive figures, and easily embed
-these in a paper. As part of this project, we are also developing the
-`astropy-timeseries <http://astropy-timeseries.readthedocs.org>`_ package which
-provides classes to represent time series as well as tools to read these in from
-files and to manipulate the time series.
+these in a paper. The package is general enough to be usable in other contexts,
+for example to embed interactive time series figures in personal web pages,
+or for use in Jupyter notebooks and Jupyter Lab.
 
-This package is still in development, but it is already possible to try out some
-of the functionality. If you run into any issues or would like to request
-features, please head over to our `issue tracker
+If you run into any issues or would like to request features, please head over
+to our `issue tracker
 <https://github.com/aperiosoftware/aas-timeseries/issues>`_.
 
 User guide
@@ -25,10 +23,11 @@ User guide
 .. toctree::
    :maxdepth: 1
 
-   installing.rst
+   installing
    getting_started
    layers
    views
-   saving.rst
-   submitting.rst
-   api.rst
+   timeaxes
+   saving
+   submitting
+   api

docs/installing.rst

@@ -1,8 +1,9 @@
 Installation
 ============
 
-To install the latest developer version of the **aas-timeseries** package as
-well as its dependencies, you can do::
+The **aas-timeseries** package requires Python 3.6 or later. To install the
+latest developer version of aas-timeseries as well as its dependencies, you can
+do::
 
     pip install git+https://github.com/aperiosoftware/aas-timeseries
 

docs/saving.rst

@@ -1,8 +1,12 @@
-Saving the interactive figure
-=============================
+Saving interactive and static figures
+=====================================
 
-To save the interactive figure to `Vega <https://vega.github.io/vega/>`_-
-compliant JSON, use::
+Saving interactive figures
+--------------------------
+
+To save the interactive figure to `Vega <https://vega.github.io/vega/>`_-compliant
+JSON, use the
+:meth:`~aas_timeseries.InteractiveTimeSeriesFigure.save_vega_json` method::
 
     fig.save_vega_json('my_figure.json')
 
@@ -12,6 +16,26 @@ the data to be embedded inside the JSON file by using::
     fig.save_vega_json('my_figure.json', embed_data=True)
 
 Finally, you can also export the JSON file and data files along with a template
-HTML file to view your interactive figure to a zip file by using::
+HTML file to view your interactive figure to a zip file by using the
+:meth:`~aas_timeseries.InteractiveTimeSeriesFigure.export_interactive_bundle`
+method::
 
     fig.export_interactive_bundle('my_figure.zip', zip_bundle=True)
+
+Saving static figures
+---------------------
+
+You can also save a static version of your plots using Matplotlib by using
+the :meth:`~aas_timeseries.InteractiveTimeSeriesFigure.save_static` method::
+
+    fig.save_static('my_figure', format='pdf')
+
+The first argument is the prefix for the final filename, rather than the full
+filename - this is because in the case where views are present, files such as
+``my_figure_view1.pdf`` will also be saved. The
+:meth:`~aas_timeseries.InteractiveTimeSeriesFigure.save_static` method supports
+all formats that are supported by the Matplotlib package.
+
+If you want to customize the appearance of the plot, such as the font type you
+can make use of the `Matplotlib rcparams
+<https://matplotlib.org/users/customizing.html#matplotlib-rcparams>`_ settings.

docs/submitting.rst

@@ -1,13 +1,16 @@
 Submitting an interactive figure to AAS Journals
 ================================================
 
-.. warning:: This package is still under development and interactive figures
-             produced here are not yet ready to be submitted to AAS Journals.
-
 To include an interactive figure in your paper, first make sure you export
-the interactive figure(s) you have produced to a zip file::
+the interactive figure(s) you have produced to a zip file (see also
+:doc:`saving`)::
 
     fig.export_interactive_bundle('my_figure.zip')
 
+and also be sure to export a static version of the figure for the PDF version
+of the paper::
+
+    fig.save_static('my_figure', format='pdf')
+
 The workflow to include your figure in the paper will be added here in the near
 future.