💡 Update docs

docs/source/CHANGELOG.rst

@@ -263,7 +263,7 @@ New
    approximated
 
 Minor
-^^^^^
+~~~~~
 
 1. Some wrappers around getting Jupyter/IPython state
 2. ``imread`` wrapper that chooses backend between ``imageio`` and

docs/source/advanced-plotting.rst

@@ -12,19 +12,19 @@ that requires more customization.
 
 If you encounter a use case you think should be supported, get in
 contact with Conrad and he can add the functionality, or become a
-`contributor </contributing>`__.
+:doc:`contributor </contributing>`.
 
 PyARPES plotting routines and techniques
 ----------------------------------------
 
--  `Stacked EDC/line plots </stack-plots>`__
--  `Fermi surfaces </fermi-surfaces>`__
--  `3D cut plots </3d-cut-plots>`__
--  `Dispersion plots </dispersion-plots>`__
--  `Spin-ARPES plots </spin-arpes>`__
--  `Ultrafast-ARPES plots </tr-arpes>`__
+-  :doc:`Stacked EDC/line plots </stack-plots>`
+-  :doc:`Fermi surfaces </fermi-surfaces>`
+-  :doc:`3D cut plots </3d-cut-plots>`
+-  :doc:`Dispersion plots </dispersion-plots>`
+-  :doc:`Spin-ARPES plots </spin-arpes>`
+-  :doc:`Ultrafast-ARPES plots </tr-arpes>`
 
 Finally, there is a discussion on:
 
--  `Plot annotations </annotations>`__
--  `Labeling and axis utilities </plotting-utilities>`__
+-  :doc:`Plot annotations </annotations>`
+-  :doc:`Labeling and axis utilities </plotting-utilities>`

docs/source/conf.py

@@ -12,7 +12,7 @@
 
 import arpes
 import arpes.config
-from arpes.endstations.plugin.ALG_main import ALGMainChamber
+from arpes.io import example_data
 from arpes.widgets import fit_initializer
 
 # -- Project information -----------------------------------------------------

docs/source/contributing.rst

@@ -29,11 +29,11 @@ What you’ll need
 
 Here’s a summary of what you’ll need to do, if you’are already familar
 with contributing to open source. If you are less familiar, much more
-detail on this is described in the `developer’s guide </dev-guide>`__.
+detail on this is described in the :doc:`developer’s guide </dev-guide>`.
 
 1.  You will need a git client, if you don’t want to use a terminal,
     have a look at Github’s `GUI Client <https://desktop.github.com/>`__
-2.  `Install an editable copy of PyARPES </dev-guide>`__
+2.  :doc:`Install an editable copy of PyARPES </dev-guide>`
 3.  Write your new analysis code, bug patch, documentation, etc.
 4.  Put it someplace reasonable in line with the project’s
     organizational principles

docs/source/fermi-surfaces.rst

@@ -21,4 +21,4 @@ surface that optionally includes the labeled high symmetry points.
 
    A labeled Fermi surface
 
-You can also `add annotations manually </annotations>`__.
+You can also :doc:`add annotations manually </annotations>`.

docs/source/getting-started.rst

@@ -19,9 +19,11 @@ Jupyter
 You should see something like this depending on the state of your
 optional dependencies:
 
+
+.. only:: html or singlehtml
 .. code:: text
 
-   [✘] Igor Pro Support:
+   [x] Igor Pro Support:
        For Igor support, install igorpy with: 
        pip install https://github.com/chstan/igorpy/tarball/712a4c4#egg=igor-0.3.1
    [✔] qt_tool Support
@@ -43,7 +45,7 @@ Loading your own data
 
 If you have the path to a piece of data you want to load as well as the
 data source it comes from (see the section on
-`plugins </writing-plugins>`__ for more detail), you can load it with
+:doc:`plugins </writing-plugins>` for more detail), you can load it with
 ``arpes.io.load_without_dataset``:
 
 .. code:: python
@@ -56,6 +58,6 @@ What’s next?
 
 With the example data in hand, you can jump into the rest of the
 examples on the site. If you’re a visual learner or are new to Jupyter
-and are running into issues, have a look at the `tutorial
-videos </example-videos>`__. Another good place to start is on the
-section for `exploration </basic-data-exploration>`__ of ARPES data.
+and are running into issues, have a look at the :doc:`tutorial videos </example-videos>`.
+Another good place to start is on the
+section for :doc:`exploration </basic-data-exploration>` of ARPES data.

docs/source/igor-pro.rst

@@ -18,8 +18,7 @@ library ```xarray`` <http://xarray.pydata.org/en/stable/>`__, which
 offers first class support for labelled, unitful volumetric data.
 
 You can learn about how PyARPES uses this library to provide a robust
-data model for ARPES in the documentation on `PyARPES
-spectra </spectra>`__.
+data model for ARPES in the documentation on :doc:`PyARPES spectra </spectra>`.
 
 Installing the patched ``igorpy``
 ---------------------------------

docs/source/index.rst

@@ -68,19 +68,19 @@ analysis tools** for
 
 These are in addition to facilities for derivatives, symmetrization, gap
 fitting, Fermi-Dirac normalization, the minimum gradient method, and
-others. Have a look through the `crash course </how-to>`__ to learn
+others. Have a look through the :doc:`crash course </how-to>` to learn
 about supported workflows.
 
 By default, PyARPES supports a variety of data formats from synchrotron
 and laser-ARPES sources including ARPES at the Advanced Light Source
 (ALS), the data produced by Scienta Omicron GmbH’s “SES Wrapper”, data
 and experiment files from Igor Pro (see in particular the section on
-`importing Igor Data </igor-pro>`__), NeXuS files, and others.
+:doc:`importing Igor Data </igor-pro>`), NeXuS files, and others.
 Additional data formats can be added via a user plugin system.
 
 If PyARPES helps you in preparing a conference presentation or
 publication, please respect the guidelines for citation laid out in the
-notes on `user contribution </contributing>`__. Contributions and
+notes on :doc:`user contribution </contributing>`. Contributions and
 suggestions from the community are also welcomed warmly.
 
 Tool Development

docs/source/installation.rst

@@ -4,7 +4,7 @@ Installation
 ============
 
 Some common issues in installation have been written up in the
-`FAQ </faq>`__.
+:doc:`FAQ </faq>`.
 
 You can install PyARPES in an editable configuration so that you can
 edit it to your needs (recommended) or as a standalone package from a
@@ -18,8 +18,7 @@ Installation from Source
 Using an installation from source is the best option if you want to
 frequently change the source of PyARPES as you work. You can use code
 available either from the main repository at
-`GitLab <https://gitlab.com/lanzara-group/python-arpes.git>`__ or the
-`GitHub mirror <https://github.com/chstan/arpes>`__.
+`GitHub <https://github.com/arafune/arpes>`__.
 
 1. **Install Miniconda or Anaconda** according to the
    `directions <https://docs.conda.io/en/latest/miniconda.html>`__

docs/source/interactive.rst

@@ -20,8 +20,9 @@ natively on one’s computer. BokehTool can be run even in hosted Jupyter
 notebooks across the internet, but data has to be pushed across HTTP,
 which means that responsivity can be hundreds of milliseconds. BokehTool
 is supplemented by a wide range of interactive analysis tools that can
-be used to `create masks </data-manipulation>`__, `set up and examine
-curve fits </curve-fitting>`__, mark symmetry points, and interactively
+be used to :doc:`create masks </data-manipulation>`, 
+:doc:`set up and examine curve fits </curve-fitting>`,
+mark symmetry points, and interactively
 set parameters for smoothing and second derivatives or curvature
 analysis, among other tasks.
 
@@ -69,7 +70,7 @@ Masking
 -------
 
 You can use ``mask()`` to get an interactive masking utility. See
-`here </data-manipulation?id=masking>`__ for more details.
+:doc:`here </data-manipulation?id=masking>` for more details.
 
 Laying Lineshapes for Curve Fitting
 -----------------------------------
@@ -80,9 +81,8 @@ to set inital locations and model structure for complicated curve fits.
 Examining Fits
 --------------
 
-Use ``.F.show()`` to get a tool that allows `interactively examining
-curve fit
-quality </curve-fitting?id=examining-fit-quality-interactively>`__.
+Use ``.F.show()`` to get a tool that allows 
+:doc:`interactively examining curve fit quality </curve-fitting?id=examining-fit-quality-interactively>`.
 
 Making Any Function Interactive
 -------------------------------

docs/source/loading-data.rst

@@ -96,7 +96,7 @@ or perform other cumbersome steps.
 I’m still running into an issue, or my use case doesn’t fit nicely
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Take a look at the `frequently asked questions </faq>`__ or get in
+Take a look at the :doc:`frequently asked questions </faq>` or get in
 contact on the `GitLab Issues
 Page <https://gitlab.com/lanzara-group/python-arpes/issues>`__ and we
 will be happy to help.

docs/source/modeling.rst

@@ -3,6 +3,6 @@ Modeling
 
 PyARPES is not and does aim to be a theory code. There are many good
 resources already in the scientific Python community, some of which we
-have included `for reference elsewhere </cmp-stack>`__.
+have included :doc:`for reference elsewhere </cmp-stack>`.
 
 TODO

docs/source/momentum-conversion.rst

@@ -18,7 +18,7 @@ angle-resolved photocurrent.
 
 In the most general case we record the electron velocity with three
 angles (you can read more about how PyARPES sets angle conventions and
-about its data format `here </spectra>`__): :math:`\phi`, the angle
+about its data format :doc:`here </spectra>`): :math:`\phi`, the angle
 along the analyzer slit in the case of hemispheres, :math:`\psi` the
 angle perpendicular to a hemispherical analyzer’s slit, and
 :math:`\alpha` a rotation angle about the spectrometer axis. In our

docs/source/plotting-utilities.rst

@@ -72,8 +72,8 @@ polarization data by default.
 These colorchoices are used intelligently by the plotting code when
 producing flat stack plots or other colored line plots. Of course, you
 can also use them manually. As an example, you can look at the section
-describing `stack plots </stack-plots>`__.
 
+describing :doc:`stack plots </stack-plots>`.
 Insets location references
 --------------------------
 

docs/source/spin-arpes.rst

@@ -63,7 +63,7 @@ PyARPES contains support for converting time of flight photoemission
 data to energy and momentum space. Our support for this currently
 supports the Lanzara Lab’s Spin-ARPES spectrometer, but support is
 largely generic to multidimensional (ARToF) and PEEM-ToF detectors,
-given an associated `data loading plugin </writing-plugins>`__.
+given an associated :doc:`data loading plugin </writing-plugins>`.
 
 .. raw:: html
 

docs/source/stack-plots.rst

@@ -1,3 +1,5 @@
+.. _stack-plots:
+
 Stack Plots
 ===========
 
@@ -51,8 +53,8 @@ Although PyARPES will attempt to make a reasonable default guess for the
 colorscale, here identifying that the stack axis is along the
 experimental temperature and giving a colorbar from 0K to room
 temperature, we can also control the colorbar and plot them onto custom
-axes with ``cbarmap=``. Utilities for colorbars are `discussed
-later </plotting-utilities>`__.
+axes with ``cbarmap=``. Utilities for colorbars are
+:doc:`discussed later </plotting-utilities>`.
 
 .. figure:: _static/flat-stack-colorbar.png
    :alt: A flat stack plot with custom colorbar

docs/source/th-arpes.rst

@@ -82,8 +82,7 @@ intensity over all values of :math:`\textbf{k}_\parallel`. Consideration
 must be given to the difference between experimentally measured angles
 and the spherical polar angles relative to
 :math:`\hat{\textbf{z}}`, and this is where we will turn our
-attention in the next section on `momentum
-conversion </momentum-conversion>`__.
+attention in the next section on :doc:`momentum conversion </momentum-conversion>`.
 
 To obtain high-quality data, ARPES experiments are conducted in an
 ultra-high vacuum chamber, typically better than

docs/source/writing-plugins-basic.rst

@@ -6,8 +6,8 @@ plugin as a demonstration of how to extend PyARPES to allow you to work
 with your lab’s data.
 
 This is the first of a two-part section on data loading and plugins in
-PyARPES. If your needs are more advanced, you can see the `second
-page </writing-plugins>`__ for more details.
+PyARPES. If your needs are more advanced, you can see the
+:doc:`second page </writing-plugins>` for more details.
 
 Loading CSV Files into the PyARPES Format
 -----------------------------------------
@@ -19,8 +19,8 @@ typically an
 or an
 `xarray.DataArray <http://xarray.pydata.org/en/stable/data-structures.html#dataarray>`__.
 
-Additionally, ARPES data must be labeled with enough `standard
-coordinates </spectra>`__ that we can convert to momentum. Let’s assume
+Additionally, ARPES data must be labeled with enough
+:doc:`standard coordinates </spectra>` that we can convert to momentum. Let’s assume
 that our data comes formatted in two files, one providing the data
 ``{name}.csv``, and one the coordinates ``{name}.coords.csv``. A
 standard data file might look like
@@ -138,5 +138,5 @@ to write data loading code for ARPES, especially in normalizing
 coordinate units (mm for all distances, rad for all angular measures),
 and ensuring the coordinates necessary to allow momentum conversion are
 attached. If you want to learn more about writing data plugins, have a
-look at the in depth description of how they work in the `second
-part </writing-plugins>`__ of this tutorial.
+look at the in depth description of how they work in the 
+:doc:`second part </writing-plugins>` of this tutorial.

docs/source/writing-plugins.rst

@@ -3,8 +3,7 @@ Adding Support for Beamlines or Lab Facilities
 
 **Note:** This is an advanced section, you can skip this unless you need
 or want to extend PyARPES to cover more data formats. Before continuing
-here, read our `intro tutorial on adding data
-sources </writing-plugins-basic>`__.
+here, read our :doc:`intro tutorial on adding data sources </writing-plugins-basic>`.
 
 One of the overarching design goals of PyARPES is to provide a
 completely uniform, pragmatic, and understandable approach to loading
@@ -31,9 +30,10 @@ without user intervention aside from invocation of
 ``prepare_raw_files()``.
 
 Internally, ``prepare_raw_files`` invokes a particular data loading
-plugin on the basis of the value of the ``location`` `spreadsheet
-column </analysis-spreadsheets>`__. This value should match the
-``PRINCIPAL_NAME`` or one of the ``ALIASES`` of a plugin. The matched
+plugin on the basis of the value of the ``location``
+:doc:`spreadsheet column </analysis-spreadsheets>`.
+This value should match the ``PRINCIPAL_NAME`` or one of the
+``ALIASES`` of a plugin. The matched
 plugin will be used to actually load the data.
 
 All plugins are loaded at configuration time (IPython kernel startup or

src/arpes/utilities/funcutils.py

@@ -88,14 +88,7 @@ def lift_dataarray_to_generic(
 ) -> Callable[Concatenate[DataType, P], DataType]:
     """A functorial decorator that lifts functions to operate over xarray types.
 
-    (xr.DataArray, *args, **kwargs) -> xr.DataArray
-
-    to one with signature
-
-    A = XrTypes
-    (A, *args, **kwargs) -> A
-
-    i.e. one that will operate either over xr.DataArrays or xr.Datasets.
+    one that will operate either over xr.DataArrays or xr.Datasets.
     """
 
     @functools.wraps(func)