Merge pull request #101 from GreenBankObservatory/pedro-devel

Updates to documentation

docs/source/examples/positionswitch.rst

@@ -168,7 +168,8 @@ The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis
     :alt: The spectrum plot zoomed in along both axes to frame a central emission line. 
 
 .. WARNING::
-    At this point, `dysh` does not handle Doppler corrections. So the frequency and velocity information will be wrong for observations requesting a reference frame other than Topocentric.
+    At this point, `dysh` does not handle Doppler corrections. 
+    So the frequency and velocity information will be offset for observations requesting a reference frame other than Topocentric.
 
 
 Removing a baseline

docs/source/for_beta_testers/beta_testing.rst

@@ -2,14 +2,40 @@
 Instructions for Beta Testers
 *****************************
 
-Instructions
+For beta testing we ask that your provide feedback in the form of:
+
+* Reporting issues. For example, if something does not work or the results are not accurate.
+* Making suggestions. For example, requesting new features.
+* Letting us know what you think. 
+
+If you are interested in beta testing `dysh`, please contact Pedro Salas ([email protected]) to be added to the beta testers list. Thanks for your interest!
+
 
 Providing feedback
 ==================
 
-If you encounter a problem with `dysh`, would like to request a new feature or enhancement or would like to leave feedback, please do so using `GitHub issues <https://github.com/GreenBankObservatory/dysh/issues>`_. There are some basic instructions of how to do this :ref:`here <for_developers/github_integrations:issues>`.
+If you encounter a problem with `dysh`, would like to request a new feature or enhancement or would like to leave feedback, please do so using `GitHub issues <https://github.com/GreenBankObservatory/dysh/issues>`_. There are some basic instructions of how to do this :ref:`here <for_developers/github_integrations:issues>`. This requires `creating a free account <https://github.com/>`_ on GitHub if you do not have one.
+
+If you prefer not to create a GitHub account, please provide your feedback to the `dysh-beta mailing list <https://groups.google.com/g/dysh-beta/about>`_, or send an email to [email protected]. Additionally, we will provide a `form for collecting feedback <https://forms.gle/27tg9adfLbDnUyz37>`_.
+
+When providing feedback, please provide
+
+* `Python` version
+* `dysh` version
+* operating system
+
+If reporting an issue please also provide
+
+* the input data (either as a link or a location inside the GBO computing environment)
+* a minimum working example to reproduce the error
+* outputs (for example, error messages or figures)
+* any additional information that might help us reproduce and understand the problem
+
 
 Example feedback
 ----------------
 
-Give and example of how to provide useful feedback when facing an issue.
+Here are examples of feedback on GitHub
+
+* reporting an issue, `Issue #88 <https://github.com/GreenBankObservatory/dysh/issues/88>`_
+* requesting a modification, `Issue #78, <https://github.com/GreenBankObservatory/dysh/issues/78>`_

docs/source/for_beta_testers/index.rst

@@ -2,7 +2,7 @@
 For Beta Testers
 ****************
 
-Here's some info that developers might find useful
+Here's some info that beta testers might find useful
 
 .. toctree::
    :maxdepth: 2

docs/source/for_developers/index.rst

@@ -8,6 +8,7 @@ Here's some info that developers might find useful
    :maxdepth: 2
 
    contributing
+   install
    doc_standards
    github_integrations
    git_workflows

docs/source/for_developers/install.rst

@@ -0,0 +1,60 @@
+***************************
+Installation for Developers
+***************************
+
+Here are the steps to install ``dysh`` if you want to develop code.
+
+We use `hatch <https://hatch.pypa.io/>`_ to manage the build environment.
+The usual caveats apply how you set up your python development environment.
+
+#. Clone the repo and install hatch.
+
+    .. code-block:: bash
+
+        $ git clone [email protected]:GreenBankObservatory/dysh.git
+        $ cd dysh
+        $ pip install hatch
+
+#. Create and activate a virtual environment with hatch and install the packages required for development.
+   The virtual environment will be created the first time; subsequent invoking ``hatch shell`` will simply load the created environment.
+
+    .. code-block:: bash
+
+        $ hatch shell
+        (dysh) $ pip install -r requirements_dev.txt
+
+#. Build and install the package
+
+    .. code-block:: bash
+
+        (dysh) $ hatch build
+        (dysh) $ pip install -e .
+
+#. You can exit this environment (which effectively had started a new shell).
+
+    .. code-block:: bash
+
+        (dysh) $ exit
+        $
+
+#. Each time when you come back in this directory without being in this virtual environment, you'll need to load the virtual environment.
+
+    .. code-block:: bash
+
+        $ hatch shell
+
+Notice you can *only* do that from within the original install directory tree.
+
+Additional Installation Options
+-------------------------------
+
+.. include:: install_developer.rst
+
+Testing
+=======
+We use `pytest` for unit and integration testing. 
+From the top-level dysh directory, run:
+
+.. code-block:: bash
+
+    $ pytest

docs/source/getting_started/install_developer.md → docs/source/for_developers/install_developer.rst

@@ -1,18 +1,21 @@
-# Developer Install
 
-The dysh README suggests a route to install **dysh** using
-**hatch**. As suggested also, there are several ways how you can
-install **dysh** for development. We give a few practical examples, all
-based on having "dyshN" directories in my ~/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.
+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.  
 
-## dysh1: native Python
+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
 
@@ -28,6 +31,8 @@ You will need initial admin privilages for this.
 
 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
@@ -45,34 +50,41 @@ After this dysh can be installed in a virtual environment controlled by hatch
 
 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
 
-     exit
-
-this will still return to the native virtual environment, so one more exit is needed to kill this 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
+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
 
@@ -85,28 +97,34 @@ Simple and self-contained, but with an anaconda3 to maintain.
      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
 
-     exit
-
-
+.. code:: bash
 
+     exit
 
+.. _dysh3:
 
-## dysh3: anaconda3 python with virtual environment
+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
 
@@ -116,7 +134,9 @@ Here is an example using an anaconda3 python, but now using hatch
      pip install hatch
 
 After this dysh can be installed in a virtual environment controlled by hatch,
-pretty much following what we did in *dysh1*:
+pretty much following what we did in :ref:`dysh1`:
+
+.. code:: bash
 
      git clone https://github.com/GreenBankObservatory/dysh
      cd dysh
@@ -130,37 +150,46 @@ pretty much following what we did in *dysh1*:
 
 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
+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
+Simple ``dysh`` Commands
+^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. code:: bash
 
      python -c 'import dysh; print(dysh.__version__)'
      python -c 'import dysh; print(dysh.__file__)'
 
-###  Building Documentation
+Building Documentation
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
 
      cd dysh/docs
      make html

docs/source/getting_started/index.rst

@@ -5,7 +5,7 @@ Getting Started
 Here's how you get started
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   install
-   install_developer
+    install
+    tutorials/index