From d2f56fa8109e9e486789420380e947db9b84d35b Mon Sep 17 00:00:00 2001 From: Ryuichi Arafune Date: Sat, 24 Feb 2024 21:22:33 +0900 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20=20Update=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/source/CHANGELOG.rst | 2 +- docs/source/advanced-plotting.rst | 18 +++++++++--------- docs/source/conf.py | 2 +- docs/source/contributing.rst | 4 ++-- docs/source/fermi-surfaces.rst | 2 +- docs/source/getting-started.rst | 12 +++++++----- docs/source/igor-pro.rst | 3 +-- docs/source/index.rst | 6 +++--- docs/source/installation.rst | 5 ++--- docs/source/interactive.rst | 12 ++++++------ docs/source/loading-data.rst | 2 +- docs/source/modeling.rst | 2 +- docs/source/momentum-conversion.rst | 2 +- docs/source/plotting-utilities.rst | 2 +- docs/source/spin-arpes.rst | 2 +- docs/source/stack-plots.rst | 6 ++++-- docs/source/th-arpes.rst | 3 +-- docs/source/writing-plugins-basic.rst | 12 ++++++------ docs/source/writing-plugins.rst | 10 +++++----- src/arpes/utilities/funcutils.py | 9 +-------- 20 files changed, 55 insertions(+), 61 deletions(-) diff --git a/docs/source/CHANGELOG.rst b/docs/source/CHANGELOG.rst index b3cf313c..afce0c8e 100644 --- a/docs/source/CHANGELOG.rst +++ b/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 diff --git a/docs/source/advanced-plotting.rst b/docs/source/advanced-plotting.rst index 68f6763b..37c2088b 100644 --- a/docs/source/advanced-plotting.rst +++ b/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 `__. +:doc:`contributor `. PyARPES plotting routines and techniques ---------------------------------------- -- `Stacked EDC/line plots `__ -- `Fermi surfaces `__ -- `3D cut plots `__ -- `Dispersion plots `__ -- `Spin-ARPES plots `__ -- `Ultrafast-ARPES plots `__ +- :doc:`Stacked EDC/line plots ` +- :doc:`Fermi surfaces ` +- :doc:`3D cut plots ` +- :doc:`Dispersion plots ` +- :doc:`Spin-ARPES plots ` +- :doc:`Ultrafast-ARPES plots ` Finally, there is a discussion on: -- `Plot annotations `__ -- `Labeling and axis utilities `__ +- :doc:`Plot annotations ` +- :doc:`Labeling and axis utilities ` diff --git a/docs/source/conf.py b/docs/source/conf.py index 2036a1ff..6227d1db 100644 --- a/docs/source/conf.py +++ b/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 ----------------------------------------------------- diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index fedf8435..a0f98cd5 100644 --- a/docs/source/contributing.rst +++ b/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 `__. +detail on this is described in the :doc:`developer’s 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 `__ -2. `Install an editable copy of PyARPES `__ +2. :doc:`Install an editable copy of PyARPES ` 3. Write your new analysis code, bug patch, documentation, etc. 4. Put it someplace reasonable in line with the project’s organizational principles diff --git a/docs/source/fermi-surfaces.rst b/docs/source/fermi-surfaces.rst index 3ff2cf12..f0fa9b53 100644 --- a/docs/source/fermi-surfaces.rst +++ b/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 `__. +You can also :doc:`add annotations manually `. diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 90da56f3..f25f7d01 100644 --- a/docs/source/getting-started.rst +++ b/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 `__ for more detail), you can load it with +:doc:`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 `__. Another good place to start is on the -section for `exploration `__ of ARPES data. +and are running into issues, have a look at the :doc:`tutorial videos `. +Another good place to start is on the +section for :doc:`exploration ` of ARPES data. diff --git a/docs/source/igor-pro.rst b/docs/source/igor-pro.rst index 50bbc450..43322c4c 100644 --- a/docs/source/igor-pro.rst +++ b/docs/source/igor-pro.rst @@ -18,8 +18,7 @@ library ```xarray`` `__, 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 `__. +data model for ARPES in the documentation on :doc:`PyARPES spectra `. Installing the patched ``igorpy`` --------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 8968d97b..2c0657b0 100644 --- a/docs/source/index.rst +++ b/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 `__ to learn +others. Have a look through the :doc:`crash course ` 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 `__), NeXuS files, and others. +:doc:`importing Igor Data `), 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 `__. Contributions and +notes on :doc:`user contribution `. Contributions and suggestions from the community are also welcomed warmly. Tool Development diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 70087b38..068059e3 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -4,7 +4,7 @@ Installation ============ Some common issues in installation have been written up in the -`FAQ `__. +:doc:`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 `__ or the -`GitHub mirror `__. +`GitHub `__. 1. **Install Miniconda or Anaconda** according to the `directions `__ diff --git a/docs/source/interactive.rst b/docs/source/interactive.rst index 25d94782..b093f6a4 100644 --- a/docs/source/interactive.rst +++ b/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 `__, `set up and examine -curve fits `__, mark symmetry points, and interactively +be used to :doc:`create masks `, +:doc:`set up and examine curve fits `, +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 `__ for more details. +:doc:`here ` 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 `__. +Use ``.F.show()`` to get a tool that allows +:doc:`interactively examining curve fit quality `. Making Any Function Interactive ------------------------------- diff --git a/docs/source/loading-data.rst b/docs/source/loading-data.rst index bdf7039e..88a38c0b 100644 --- a/docs/source/loading-data.rst +++ b/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 `__ or get in +Take a look at the :doc:`frequently asked questions ` or get in contact on the `GitLab Issues Page `__ and we will be happy to help. diff --git a/docs/source/modeling.rst b/docs/source/modeling.rst index 44c4176b..0ac89a30 100644 --- a/docs/source/modeling.rst +++ b/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 `__. +have included :doc:`for reference elsewhere `. TODO diff --git a/docs/source/momentum-conversion.rst b/docs/source/momentum-conversion.rst index 48555219..fcee7307 100644 --- a/docs/source/momentum-conversion.rst +++ b/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 `__): :math:`\phi`, the angle +about its data format :doc:`here `): :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 diff --git a/docs/source/plotting-utilities.rst b/docs/source/plotting-utilities.rst index 3b0c3ae0..f99c3d3e 100644 --- a/docs/source/plotting-utilities.rst +++ b/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 `__. +describing :doc:`stack plots `. Insets location references -------------------------- diff --git a/docs/source/spin-arpes.rst b/docs/source/spin-arpes.rst index 90a52447..34e65135 100644 --- a/docs/source/spin-arpes.rst +++ b/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 `__. +given an associated :doc:`data loading plugin `. .. raw:: html diff --git a/docs/source/stack-plots.rst b/docs/source/stack-plots.rst index b38fcfb4..9414daee 100644 --- a/docs/source/stack-plots.rst +++ b/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 `__. +axes with ``cbarmap=``. Utilities for colorbars are +:doc:`discussed later `. .. figure:: _static/flat-stack-colorbar.png :alt: A flat stack plot with custom colorbar diff --git a/docs/source/th-arpes.rst b/docs/source/th-arpes.rst index c267401a..a9a9ecc6 100644 --- a/docs/source/th-arpes.rst +++ b/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 `__. +attention in the next section on :doc:`momentum conversion `. To obtain high-quality data, ARPES experiments are conducted in an ultra-high vacuum chamber, typically better than diff --git a/docs/source/writing-plugins-basic.rst b/docs/source/writing-plugins-basic.rst index b8a21c03..38b66403 100644 --- a/docs/source/writing-plugins-basic.rst +++ b/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 `__ for more details. +PyARPES. If your needs are more advanced, you can see the +:doc:`second page ` for more details. Loading CSV Files into the PyARPES Format ----------------------------------------- @@ -19,8 +19,8 @@ typically an or an `xarray.DataArray `__. -Additionally, ARPES data must be labeled with enough `standard -coordinates `__ that we can convert to momentum. Let’s assume +Additionally, ARPES data must be labeled with enough +:doc:`standard coordinates ` 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 `__ of this tutorial. +look at the in depth description of how they work in the +:doc:`second part ` of this tutorial. diff --git a/docs/source/writing-plugins.rst b/docs/source/writing-plugins.rst index 513f5c4e..1e0ca024 100644 --- a/docs/source/writing-plugins.rst +++ b/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 `__. +here, read our :doc:`intro tutorial on adding data sources `. 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 `__. 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 `. +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 diff --git a/src/arpes/utilities/funcutils.py b/src/arpes/utilities/funcutils.py index 4dc4bac3..6bad02c6 100644 --- a/src/arpes/utilities/funcutils.py +++ b/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)