Merge pull request #450 from mhvk/link-to-baseband-tasks

Link to baseband tasks

baseband/io/__init__.py

@@ -3,7 +3,8 @@
 
 Contains general ``open`` and ``file_info`` functions that can iterate
 over possible formats to determine which is the right one, including
-possible formats discovered via entry point 'baseband.io'.
+possible formats discovered via entry point 'baseband.io', such as
+the `~baseband_tasks.io.hdf5` module from the baseband-tasks_ package.
 
 Any 'baseband.io' entry points are treated as possible formats if they
 point to a module (e.g., 'vdif = baseband.vdif').  Any entries that

baseband/tasks/__init__.py

@@ -2,7 +2,7 @@
 """Analysis tasks.
 
 The tasks are imported via plugins discovered via entry point
-'baseband.tasks', such as are provided by the ``baseband-tasks``
+'baseband.tasks', such as are provided by the baseband-tasks_
 package.  A special rule for the entry points is that if it points
 to ``__all__``, all items from that list will be imported.
 Furthermore, if any name starts with '_', it is not imported.

docs/conf.py

@@ -57,13 +57,21 @@
 # major.minor, call `check_sphinx_version("x.y.z")` here.
 # check_sphinx_version("1.2.1")
 
+# add any custom intersphinx mappings
+intersphinx_mapping['baseband_tasks'] = (
+    'https://baseband.readthedocs.io/projects/baseband-tasks/en/stable/', None)
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns.append('_templates')
 
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
 rst_epilog += """
+.. _Python: https://www.python.org/
+.. _Astropy: https://www.astropy.org
+.. _NumPy: https://numpy.org
+.. _baseband-tasks: https://baseband.readthedocs.io/projects/baseband-tasks/
 .. |minimum_python_version| replace:: {0.__minimum_python_version__}
 .. |minimum_astropy_version| replace:: {0.__minimum_astropy_version__}
 """.format(baseband)

docs/index.rst

@@ -6,7 +6,7 @@ Baseband
 
 Welcome to the Baseband documentation!  Baseband is a package
 `affiliated <https://www.astropy.org/affiliated/index.html>`_ with the
-`Astropy project <https://www.astropy.org>`_ for reading and
+Astropy_ project for reading and
 writing VLBI and other radio baseband files, with the aim of simplifying and
 streamlining data conversion and standardization.  It provides:
 
@@ -17,6 +17,10 @@ streamlining data conversion and standardization.  It provides:
 - The ability to read from and write to an ordered sequence of files as if it
   was a single file.
 
+It can be extended with the more experimental baseband-tasks_ package,
+which provides tasks to, e.g., `~baseband_tasks.channelize.Channelize`
+or `~baseband_tasks.dispersion.Dedisperse` sample streams.
+
 If you used this package in your research, please cite it via DOI
 `10.5281/zenodo.1214268 <https://doi.org/10.5281/zenodo.1214268>`_.
 

docs/install.rst

@@ -11,8 +11,8 @@ Requirements
 
 Baseband requires:
 
-- `Python <https://www.python.org/>`_ |minimum_python_version| or later
-- `Astropy`_ |minimum_astropy_version| or later
+- Python_ |minimum_python_version| or later
+- Astropy_ |minimum_astropy_version| or later
 - `entrypoints <https://entrypoints.readthedocs.io/en/latest/>`_
 
 .. _install_baseband:
@@ -26,7 +26,10 @@ run::
     pip3 install baseband
 
 Here, include a ``--user`` flag if you are installing for yourself
-outside of a virtual environment.
+outside of a virtual environment.  You can also add a trailing
+``[all]`` to install also the `baseband-tasks`_ package (and all of
+its dependencies), which provides analysis tasks and I/O support for
+`~baseband_tasks.io.hdf5`.
 
 Obtaining Source Code
 ---------------------

docs/tutorials/getting_started.rst

@@ -13,8 +13,11 @@ Baseband <using_baseband>`.
 For installation instructions, please see :ref:`Installing Baseband
 <install_baseband>`.
 
-When using Baseband, we typically will also use `numpy`, `astropy.units`, and
-`astropy.time.Time`. Let's import all of these::
+When using Baseband, we typically will also use
+numpy_, the `astropy.units <https://docs.astropy.org/en/stable/units>`_ module,
+and :class:`~astropy.time.Time` from the
+`astropy.time <https://docs.astropy.org/en/stable/time>`_ module.
+Let's import all of these::
 
     >>> import baseband
     >>> import numpy as np
@@ -30,12 +33,14 @@ For this tutorial, we'll use two sample files::
 
     >>> from baseband.data import SAMPLE_VDIF, SAMPLE_MARK5B
 
-The first file is a VDIF one created from `EVN <https://www.evlbi.org/>`_/`VLBA
-<https://public.nrao.edu/telescopes/vlba/>`_ observations of `Black Widow
-pulsar PSR B1957+20 <https://en.wikipedia.org/wiki/Black_Widow_Pulsar>`_,
-while the second is a Mark 5B from EVN/`WSRT
-<https://www.astron.nl/radio-observatory/public/public-0>`_ observations of the
-same pulsar.
+The first file is a VDIF one created from EVN_/VLBA_ observations of
+`Black Widow pulsar PSR B1957+20
+<https://en.wikipedia.org/wiki/Black_Widow_Pulsar>`_, while the second
+is a Mark 5B from EVN_/WSRT_ observations of the same pulsar.
+
+.. _EVN: https://www.evlbi.org/
+.. _VLBA: https://public.nrao.edu/telescopes/vlba/
+.. _WSRT: https://www.astron.nl/radio-observatory/public/public-0
 
 To open the VDIF file::
 

docs/tutorials/using_baseband.rst

@@ -24,8 +24,9 @@ basics of :ref:`inspecting files <using_baseband_inspecting>`, :ref:`reading
 <using_baseband_reading>` from and :ref:`writing <using_baseband_writing>`
 to files, :ref:`converting <using_baseband_converting>` from one format
 to another, and :ref:`diagnosing problems <using_baseband_problems>`.
-We assume that Baseband as well as `NumPy <https://www.numpy.org/>`_ and the
-`Astropy`_ units module have been imported::
+We assume that Baseband as well as numpy_ and the
+`astropy.units <https://docs.astropy.org/en/stable/units>`_ module
+have been imported::
 
     >>> import baseband
     >>> import numpy as np

setup.cfg

@@ -32,6 +32,8 @@ baseband.io =
     gsb = baseband.gsb
 
 [options.extras_require]
+all =
+    baseband-tasks[all]
 test =
     pytest-astropy-header
     pytest-doctestplus