From 36cabebeea2ee04e34b2e0856598a97dbd0cbfea Mon Sep 17 00:00:00 2001 From: vcatlett-nrao Date: Wed, 6 Dec 2023 18:25:19 -0500 Subject: [PATCH 1/3] Fix Sphinx warnings --- .gitignore | 1 + docs/source/for_developers/install.rst | 198 +++++++++++++++++- .../for_developers/install_developer.rst | 196 ----------------- .../getting_started/tutorials/GBT/index.rst | 1 + .../getting_started/tutorials/index.rst | 2 +- docs/source/index.rst | 5 +- src/dysh/plot/specplot.py | 14 +- src/dysh/spectra/core.py | 2 +- 8 files changed, 212 insertions(+), 207 deletions(-) delete mode 100644 docs/source/for_developers/install_developer.rst diff --git a/.gitignore b/.gitignore index 6c928cf6..2c1e67ed 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ *.fits .ignore/ docs/source/_build/ +docs/*env*/ # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/docs/source/for_developers/install.rst b/docs/source/for_developers/install.rst index 25b23ccb..e6eca46a 100644 --- a/docs/source/for_developers/install.rst +++ b/docs/source/for_developers/install.rst @@ -45,13 +45,209 @@ The usual caveats apply how you set up your python development environment. Notice you can *only* do that from within the original install directory tree. + Additional Installation Options ------------------------------- -.. include:: install_developer.rst +The previous instructions (and the ``dysh`` README) suggest a route to install ``dysh`` using `hatch`. +However, there are several ways how you can install ``dysh`` for development. +We give a few practical examples, all based on having "dyshN" directories in a ~/GBT directory. +It is imperative that a developer install takes place in a shielded environment, generally using a virtual environment. + +We list a few, but if you found another approach, please share. + +.. _dysh1: + +dysh1: native Python +^^^^^^^^^^^^^^^^^^^^ + +Here is an example using native python on a vanilla Ubuntu system (python version 3.11 may be different). +You will need initial admin privilages for this. + +.. code:: bash + + # first ensure your native python has at least a way to run pip and allow a venv + sudo apt install python3 python3-pip ipython3 python3.11-venv jupyter-core + + # setup a venv, for example in a $HOME/venv hierarchy + mkdir -p $HOME/venv + python3 -m venv $HOME/venv/dysh1 + + # activate this venv + source $HOME/venv/dysh1/bin/activate + + # install hatch + pip install hatch notebook + +After this dysh can be installed in a virtual environment controlled by hatch + +.. code:: bash + + mkdir ~/GBT/dysh1 + cd ~/GBT/dysh1 + git clone https://github.com/GreenBankObservatory/dysh + cd dysh + + # setup dysh with hatch (be sure to be in the dysh directory) + hatch shell + pip install -r requirements_dev.txt + # some warning about running ipython + pip install -r docs/requirements.txt + hatch build + pip install -e . + ipython # this initially gave a matplotlib error, but it went away + exit + +Any time development is needed: + +.. code:: bash + + source $HOME/venv/dysh1/bin/activate + cd ~/GBT/dysh1/dysh + hatch shell + +and as always, verify it's there: + +.. code:: bash + + python -c 'import dysh; print(dysh.__version__)' + echo "git BRANCH: $(git branch --show-current) HEAD: $(git rev-list --count HEAD)" + +and when done, exit the hatch sub-shell + +.. code:: bash + + exit + +this will still return to the native virtual environment, so one more exit is needed to kill this shell + +.. code:: bash + + exit + +.. _dysh2: + +dysh2: anaconda3 python +^^^^^^^^^^^^^^^^^^^^^^^ + +Here is an example using an anaconda3 python, no virtual environments, no hatch, no nothing. +Simple and self-contained, but with an anaconda3 to maintain. + +.. code:: bash + + mkdir ~/GBT/dysh2 + cd ~/GBT/dysh2 + + ../install_anaconda3 # DM me for a copy + source python_start.sh + + git clone https://github.com/GreenBankObservatory/dysh + cd dysh + pip install -r requirements_dev.txt + pip install -r docs/requirements.txt + pip install -e . + +any time development is needed: + +.. code:: bash + + source ~/GBT/dysh2/python_start.sh + +and verify + +.. code:: bash + + python -c 'import dysh; print(dysh.__version__)' + echo "git BRANCH: $(git branch --show-current) HEAD: $(git rev-list --count HEAD)" + +and when done, exit will terminate the shell + +.. code:: bash + + exit + +.. _dysh3: + +dysh3: anaconda3 python with virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here is an example using an anaconda3 python, but now using hatch + +.. code:: bash + + mkdir ~/GBT/dysh3 + cd ~/GBT/dysh3 + + ../install_anaconda3 # DM me for a copy + source python_start.sh + + pip install hatch + +After this dysh can be installed in a virtual environment controlled by hatch, +pretty much following what we did in :ref:`dysh1`: + +.. code:: bash + + git clone https://github.com/GreenBankObservatory/dysh + cd dysh + + # setup dysh with hatch (be sure to be in the dysh directory) + hatch shell + pip install -r requirements_dev.txt + pip install -r docs/requirements.txt + hatch build + pip install -e . + +and verify + +.. code:: bash + + python -c 'import dysh; print(dysh.__version__)' + echo "git BRANCH: $(git branch --show-current) HEAD: $(git rev-list --count HEAD)" + +and when done, exit will terminate the shell + +.. code:: bash + + exit + + +Any time development is needed: + +.. code:: bash + + source $HOME/GBT/dysh3/python_start.sh + cd ~/GBT/dysh3/dysh + hatch shell + + +Sample workflows +---------------- + +Minor issue: with hatch, if you're not in the code tree (much like git) you don't know +where your code tree is. Do we need peter's "rc" files. Do we need a module file? + + +Simple ``dysh`` Commands +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + python -c 'import dysh; print(dysh.__version__)' + python -c 'import dysh; print(dysh.__file__)' + +Building Documentation +^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + cd dysh/docs + make html + xdg-open _build/html/index.html Testing ======= + We use `pytest` for unit and integration testing. From the top-level dysh directory, run: diff --git a/docs/source/for_developers/install_developer.rst b/docs/source/for_developers/install_developer.rst deleted file mode 100644 index ee666f1a..00000000 --- a/docs/source/for_developers/install_developer.rst +++ /dev/null @@ -1,196 +0,0 @@ - -The previous instructions (and the ``dysh`` README) suggest a route to install ``dysh`` using `hatch`. -However, there are several ways how you can install ``dysh`` for development. -We give a few practical examples, all based on having "dyshN" directories in a ~/GBT directory. -It is imperative that a developer install takes place in a shielded environment, generally using a virtual environment. - -We list a few, but if you found another approach, please share. - -.. _dysh1: - -dysh1: native Python -^^^^^^^^^^^^^^^^^^^^ - -Here is an example using native python on a vanilla Ubuntu system (python version 3.11 may be different). -You will need initial admin privilages for this. - -.. code:: bash - - # first ensure your native python has at least a way to run pip and allow a venv - sudo apt install python3 python3-pip ipython3 python3.11-venv jupyter-core - - # setup a venv, for example in a $HOME/venv hierarchy - mkdir -p $HOME/venv - python3 -m venv $HOME/venv/dysh1 - - # activate this venv - source $HOME/venv/dysh1/bin/activate - - # install hatch - pip install hatch notebook - -After this dysh can be installed in a virtual environment controlled by hatch - -.. code:: bash - - mkdir ~/GBT/dysh1 - cd ~/GBT/dysh1 - git clone https://github.com/GreenBankObservatory/dysh - cd dysh - - # setup dysh with hatch (be sure to be in the dysh directory) - hatch shell - pip install -r requirements_dev.txt - # some warning about running ipython - pip install -r docs/requirements.txt - hatch build - pip install -e . - ipython # this initially gave a matplotlib error, but it went away - exit - -Any time development is needed: - -.. code:: bash - - source $HOME/venv/dysh1/bin/activate - cd ~/GBT/dysh1/dysh - hatch shell - -and as always, verify it's there: - -.. code:: bash - - python -c 'import dysh; print(dysh.__version__)' - echo "git BRANCH: $(git branch --show-current) HEAD: $(git rev-list --count HEAD)" - -and when done, exit the hatch sub-shell - -.. code:: bash - - exit - -this will still return to the native virtual environment, so one more exit is needed to kill this shell - -.. code:: bash - - exit - -.. _dysh2: - -dysh2: anaconda3 python -^^^^^^^^^^^^^^^^^^^^^^^ - -Here is an example using an anaconda3 python, no virtual environments, no hatch, no nothing. -Simple and self-contained, but with an anaconda3 to maintain. - -.. code:: bash - - mkdir ~/GBT/dysh2 - cd ~/GBT/dysh2 - - ../install_anaconda3 # DM me for a copy - source python_start.sh - - git clone https://github.com/GreenBankObservatory/dysh - cd dysh - pip install -r requirements_dev.txt - pip install -r docs/requirements.txt - pip install -e . - -any time development is needed: - -.. code:: bash - - source ~/GBT/dysh2/python_start.sh - -and verify - -.. code:: bash - - python -c 'import dysh; print(dysh.__version__)' - echo "git BRANCH: $(git branch --show-current) HEAD: $(git rev-list --count HEAD)" - -and when done, exit will terminate the shell - -.. code:: bash - - exit - -.. _dysh3: - -dysh3: anaconda3 python with virtual environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Here is an example using an anaconda3 python, but now using hatch - -.. code:: bash - - mkdir ~/GBT/dysh3 - cd ~/GBT/dysh3 - - ../install_anaconda3 # DM me for a copy - source python_start.sh - - pip install hatch - -After this dysh can be installed in a virtual environment controlled by hatch, -pretty much following what we did in :ref:`dysh1`: - -.. code:: bash - - git clone https://github.com/GreenBankObservatory/dysh - cd dysh - - # setup dysh with hatch (be sure to be in the dysh directory) - hatch shell - pip install -r requirements_dev.txt - pip install -r docs/requirements.txt - hatch build - pip install -e . - -and verify - -.. code:: bash - - python -c 'import dysh; print(dysh.__version__)' - echo "git BRANCH: $(git branch --show-current) HEAD: $(git rev-list --count HEAD)" - -and when done, exit will terminate the shell - -.. code:: bash - - exit - - -Any time development is needed: - -.. code:: bash - - source $HOME/GBT/dysh3/python_start.sh - cd ~/GBT/dysh3/dysh - hatch shell - - -Sample workflows ----------------- - -Minor issue: with hatch, if you're not in the code tree (much like git) you don't know -where your code tree is. Do we need peter's "rc" files. Do we need a module file? - - -Simple ``dysh`` Commands -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: bash - - python -c 'import dysh; print(dysh.__version__)' - python -c 'import dysh; print(dysh.__file__)' - -Building Documentation -^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: bash - - cd dysh/docs - make html - xdg-open _build/html/index.html diff --git a/docs/source/getting_started/tutorials/GBT/index.rst b/docs/source/getting_started/tutorials/GBT/index.rst index deafffec..7aae1644 100644 --- a/docs/source/getting_started/tutorials/GBT/index.rst +++ b/docs/source/getting_started/tutorials/GBT/index.rst @@ -4,4 +4,5 @@ Tutorials for GBT Data .. toctree:: :maxdepth: 2 + tutorial-positionswitch diff --git a/docs/source/getting_started/tutorials/index.rst b/docs/source/getting_started/tutorials/index.rst index 57c7bf1e..fcdab94c 100644 --- a/docs/source/getting_started/tutorials/index.rst +++ b/docs/source/getting_started/tutorials/index.rst @@ -7,4 +7,4 @@ Tutorials on how to use `dysh`. .. toctree:: :maxdepth: 1 - GBT/tutorial-positionswitch + GBT/index diff --git a/docs/source/index.rst b/docs/source/index.rst index 2b2e6bc5..1973b30f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,7 @@ -****************** +********************** ``dysh`` Documentation -****************** +********************** + ``dysh`` is a Python spectral line data reduction and analysis program for singledish data with specific emphasis on data from the Green Bank Telescope. It is currently under development in collaboration between the `Green Bank Observatory `_ and the Laboratory for Millimeter-Wave Astronomy (LMA) diff --git a/src/dysh/plot/specplot.py b/src/dysh/plot/specplot.py index ed472d43..863c05d5 100644 --- a/src/dysh/plot/specplot.py +++ b/src/dysh/plot/specplot.py @@ -1,4 +1,6 @@ -"""Plot a spectrum using matplotlib""" +""" +Plot a spectrum using matplotlib +""" import astropy.units as u import matplotlib.pyplot as plt @@ -7,9 +9,9 @@ class SpectrumPlot: r""" - The SpectrumPlot class is for simple plotting of a ~spectrum.Spectrum - using matplotlib functions. Plots attributes are modified using keywords - (**kwargs) described below SpectrumPlot will attempt to make smart default + The SpectrumPlot class is for simple plotting of a `~spectrum.Spectrum` + using matplotlib functions. Plots attributes are modified using keywords + (\*\*kwargs) described below SpectrumPlot will attempt to make smart default choices for the plot if no additional keywords are given. The attributes are "sticky" meaning that an attribute set via instantiation or by the `plot()` method will stay set until changed @@ -24,9 +26,9 @@ class SpectrumPlot: Other Parameters ---------------- - xaxis_unit : str or ~astropy.unit.Unit + xaxis_unit : str or `~astropy.unit.Unit` The units to use on the x-axis, e.g. "km/s" to plot velocity - yaxis_unit : str or ~astropy.unit.Unit + yaxis_unit : str or `~astropy.unit.Unit` The units to use on the y-axis xmin : float Minimum x-axis value diff --git a/src/dysh/spectra/core.py b/src/dysh/spectra/core.py index b85088ea..12fceebd 100644 --- a/src/dysh/spectra/core.py +++ b/src/dysh/spectra/core.py @@ -240,7 +240,7 @@ def baseline(spectrum, order, exclude=None, **kwargs): model : str One of 'polynomial' or 'chebyshev', Default: 'polynomial' fitter : `~astropy.fitting._FitterMeta` - The fitter to use. Default: `~astropy.fitter.LinearLSQFitter` (with `calc_uncertaintes=True). Be care when choosing a different fitter to be sure it is optimized for this problem. + The fitter to use. Default: `~astropy.fitter.LinearLSQFitter` (with `calc_uncertaintes=True`). Be care when choosing a different fitter to be sure it is optimized for this problem. Returns ------- From 70f940e0c01fa3b673340fad44ee26efd9537f1d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 6 Dec 2023 23:27:35 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/getting_started/tutorials/GBT/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting_started/tutorials/GBT/index.rst b/docs/source/getting_started/tutorials/GBT/index.rst index 7aae1644..e7574f09 100644 --- a/docs/source/getting_started/tutorials/GBT/index.rst +++ b/docs/source/getting_started/tutorials/GBT/index.rst @@ -4,5 +4,5 @@ Tutorials for GBT Data .. toctree:: :maxdepth: 2 - + tutorial-positionswitch From 553db1701074e28274033683745b1f315c375380 Mon Sep 17 00:00:00 2001 From: Victoria Catlett <106776095+vcatlett@users.noreply.github.com> Date: Thu, 7 Dec 2023 10:51:57 -0500 Subject: [PATCH 3/3] Update .gitignore Co-authored-by: Thomas Chamberlin --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 2c1e67ed..6c928cf6 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ *.fits .ignore/ docs/source/_build/ -docs/*env*/ # Byte-compiled / optimized / DLL files __pycache__/