docs: update docs look and feel

AUTHORS.rst

@@ -1,5 +1,5 @@
 =======
-AUTHORS
+Authors
 =======
 
 * HERA-Team - https://github.com/HERA-Team

CHANGELOG.rst

@@ -14,39 +14,25 @@ Fixed
 Changed
 -------
 
-- All functions that take frequencies and LSTs as arguments have had \
-  their signatures changed to func(lsts, freqs, \*args, \*\*kwargs)
-
-- Changes to handling of functions which employ a fringe or delay \
-  filtering step with variable keywords for the filters used. Filter \
-  keywords are now specified with individual dictionaries called \
-  ``delay_filter_kwargs`` or ``fringe_filter_kwargs``, depending on \
-  the filter used.
-   - Functions affected by this change are as follows:
-      - ``diffuse_foreground``
-      - ``noiselike_eor``
-
-- Changes to parameters that shared the same name but represented \
-  conceptually different objects in various functions. Functions \
-  affected by this are as follows:
-   - ``utils.rough_delay_filter``
-   - ``utils.rough_fringe_filter``
-   - Most RFI functions
-
-- The ``io.empty_uvdata`` function had its default keyword values \
-  set to ``None``. The keywords accepted by this function have also \
-  been changed to match their names in \
-  ``pyuvsim.simsetup.initialize_uvdata_from_keywords``
-
-- Changes to parameters in most RFI models. Optional parameters that \
-  are common to many models (but should not share the same name), such \
-  as ``std`` or ``chance``, have been prefixed with the model name and \
-  an underscore (e.g. ``dtv_chance``). Various other parameters have \
-  been renamed for consistency/clarity. Note that the ``freq_min`` and \
-  ``freq_max`` parameters for ``rfi_dtv`` have been replaced by the \
-  single parameter ``dtv_band``, which is a tuple denoting the edges of \
-  the DTV band in GHz.
-
+- All functions that take frequencies and LSTs as arguments have had their signatures
+  changed to ``func(lsts, freqs, \*args, \*\*kwargs)``.
+- Changes to handling of functions which employ a fringe or delay filtering step with
+  variable keywords for the filters used. Filter keywords are now specified with
+  individual dictionaries called ``delay_filter_kwargs`` or ``fringe_filter_kwargs``,
+  depending on the filter used. Functions affected by this change are
+  ``diffuse_foreground`` and ``noiselike_eor``.
+- Changes to parameters that shared the same name but represented conceptually different
+  objects in various functions. Functions affected by this are:
+  ``utils.rough_delay_filter``, ``utils.rough_fringe_filter`` and most RFI functions.
+- The :func:`~hera_sim.io.empty_uvdata` function had its default keyword values
+  set to ``None``. The keywords accepted by this function have also been changed to
+  match their names in ``pyuvsim.simsetup.initialize_uvdata_from_keywords``.
+- Changes to parameters in most RFI models. Optional parameters that are common to many
+  models (but should not share the same name), such as ``std`` or ``chance``, have been
+  prefixed with the model name and an underscore (e.g. ``dtv_chance``). Various other
+  parameters have been renamed for consistency/clarity. Note that the ``freq_min`` and
+  ``freq_max`` parameters for ``rfi_dtv`` have been replaced by the single parameter
+  ``dtv_band``, which is a tuple denoting the edges of the DTV band in GHz.
 - Functions in ``utils`` now use ``freqs`` instead of ``fqs``.
 
 v0.3.0 [2019.12.10]

docs/Makefile

@@ -1,20 +1,154 @@
-# Minimal makefile for Sphinx documentation
+# Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = hera_sim
-SOURCEDIR     = .
+PAPER         =
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+	-rm -rf reference/_autosummary/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/hmf.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/hmf.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/hmf"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/hmf"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
 
-.PHONY: help Makefile
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/conf.py

@@ -123,7 +123,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # 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
@@ -214,3 +214,5 @@
 napoleon_use_ivar = True
 napoleon_use_rtype = False
 napoleon_use_param = False
+
+autodoc_typehints = "both"  # put typehints in the signature AND description.

docs/notes_for_developers.rst

@@ -2,9 +2,5 @@
 Developing ``hera_sim``
 =======================
 
-``hera_sim`` broadly follows the best-practices laid out in XXX.
-
-.. todo:: where is that best-practices doc?
-
-
-All docstrings should be written in `Google docstring format <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_.
+All docstrings should be written in
+`Numpy docstring format <https://numpydoc.readthedocs.io/en/latest/format.html>`_.

docs/tutorials.rst

@@ -29,3 +29,11 @@ command line:
    :maxdepth: 2
 
    tutorials/hera_sim_cli
+
+The following tutorial will give you an overview of how to simulate visibilities from
+sky models using ``hera_sim``:
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/visibility_simulator

hera_sim/components.py

@@ -77,6 +77,7 @@ class determine how to apply the effect simulated by
             """
             super().__init_subclass__(**kwargs)
             cls._update_call_docstring()
+            #: whether the systematic multiplies existing visibilities.
             cls.is_multiplicative = is_multiplicative
             if not is_abstract:
                 cls.__base__._models[cls.__name__] = cls

hera_sim/interpolators.py

@@ -258,7 +258,7 @@ class FreqInterpolator(Interpolator):
 
     Raises
     ------
-    AssertionError:
+    AssertionError
         This is raised if the choice of interpolator and the required type
         of the ref_file do not agree (i.e. trying to make a 'poly1d' object
         using a .npz file as a reference). An AssertionError is also raised

hera_sim/sigchain.py

@@ -2,7 +2,7 @@
 
 import numpy as np
 import warnings
-from typing import Dict, Tuple
+from typing import Dict, Tuple, Union
 
 from scipy import stats
 
@@ -530,7 +530,9 @@ def __call__(self, freqs, **kwargs):
 
 
 def apply_gains(
-    vis: [float, np.ndarray], gains: Dict[int, [float, np.ndarray]], bl: Tuple[int, int]
+    vis: Union[float, np.ndarray],
+    gains: Dict[int, Union[float, np.ndarray]],
+    bl: Tuple[int, int],
 ) -> np.ndarray:
     """Apply antenna-based gains to a visibility.
 

hera_sim/visibilities/simulators.py

@@ -85,12 +85,12 @@ class VisibilitySimulator(metaclass=ABCMeta):
         product of the responses of two input antenna beams.
     """
 
-    # Whether this particular simulator has the ability to simulate point
-    # sources directly.
+    #: Whether this particular simulator has the ability to simulate point
+    #: sources directly.
     point_source_ability = True
 
-    # Whether this particular simulator has the ability to simulate diffuse
-    # maps directly.
+    #: Whether this particular simulator has the ability to simulate diffuse
+    #: maps directly.
     diffuse_ability = True
 
     def __init__(