edits to manuals and tutorials

GeminiDRSoftware · Mar 20, 2024 · a0243c2 · a0243c2
1 parent 3a880e2
commit a0243c2
Show file tree

Hide file tree

Showing 7 changed files with 30 additions and 21 deletions.
diff --git a/astrodata/doc/cheatsheet.rst b/astrodata/doc/cheatsheet.rst
@@ -13,7 +13,7 @@ Cheat Sheet
 A data package is available for download if you wish to run the examples
 included in this cheat sheet.  Download it at:
 
-    `<http://www.gemini.edu/sciops/data/software/datapkgs/ad_usermanual_datapkg-v1.tar>`_
+    `<https://www.gemini.edu/sciops/data/software/datapkgs/ad_usermanual_datapkg-v1.tar>`_
 
 To unpack::
 

diff --git a/recipe_system/doc/rs_ProgManual/.readthedocs.yaml b/recipe_system/doc/rs_ProgManual/.readthedocs.yaml
@@ -27,4 +27,6 @@ sphinx:
 python:
    install:
    - requirements: requirements.txt
-   - requirements: doc/requirements.txt
+   - requirements: doc/requirements.txt
+   - method: pip
+     path: .
diff --git a/recipe_system/doc/rs_ProgManual/conf.py b/recipe_system/doc/rs_ProgManual/conf.py
@@ -435,4 +435,6 @@ def setup(app):
 .. |RSUser|  replace:: :raw-html:`<a href="http://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/">Recipe System Users Manual</a>`
 .. |astrodataprog| replace:: :raw-html:`<a href="https://astrodata.readthedocs.io/en/{v}/progmanual/index.html">Astrodata Programmer Manual</a>`
 
+.. |DRAGONS| replace:: :raw-html:`<a href="http://dragons.readthedocs.io/en/{v}/">DRAGONS</a>`
+
 """.format(v = rtdurl)
diff --git a/recipe_system/doc/rs_ProgManual/index.rst b/recipe_system/doc/rs_ProgManual/index.rst
@@ -10,6 +10,8 @@ Recipe System Programmers Manual
 
    PIPE-USER-108_RSProgManual
 
+[Return to the main |DRAGONS| page.]
+
 .. toctree::
    :maxdepth: 2
    :caption: Table of Contents

diff --git a/recipe_system/doc/rs_UsersManual/conf.py b/recipe_system/doc/rs_UsersManual/conf.py
@@ -298,4 +298,6 @@ def setup(app):
 .. |astrodataprog| replace:: :raw-html:`<a href="https://astrodata.readthedocs.io/en/{v}/progmanual/index.html">Astrodata Programmer Manual</a>`
 .. |RSProg|  replace:: :raw-html:`<a href="http://dragons-recipe-system-programmers-manual.readthedocs.io/en/{v}/">Recipe System Programmers Manual</a>`
 
+.. |DRAGONS| replace:: :raw-html:`<a href="http://dragons.readthedocs.io/en/{v}/">DRAGONS</a>`
+
 """.format(v = rtdurl)
diff --git a/recipe_system/doc/rs_UsersManual/index.rst b/recipe_system/doc/rs_UsersManual/index.rst
@@ -11,6 +11,8 @@ Recipe System User Manual
 
    PIPE-USER-109_RSUserManual
 
+[Return to the main |DRAGONS| page.]
+
 .. toctree::
    :maxdepth: 2
    :caption: Table of Contents

diff --git a/recipe_system/doc/rs_UsersManual/install.rst b/recipe_system/doc/rs_UsersManual/install.rst
@@ -35,14 +35,15 @@ The use of the ``bash`` shell is recommended.
 Install Miniforge
 =================
 
-We recommend using Miniforge instead of Anaconda.  It is smaller and install
+We recommend using Miniforge instead of Anaconda.  It is smaller and installs
 contents from conda-forge which is now our main channel for python packages.
 The overall size of the installation will therefore be much smaller than
 a full Anaconda installation.  The instructions below are for Miniforge.
 
 Anaconda will work just fine too if you prefer or have a business need for
-it.  We just don't provide instructions for its installation.  Miniforge or
-Anaconda will not impact the DRAGONS installation.
+it.  We just don't provide instructions for its installation.  Whether you use
+Miniforge or Anaconda will not impact the DRAGONS installation as long as
+your using the correct conda channels.
 
 Download and install Miniforge
 ------------------------------
@@ -74,24 +75,23 @@ installer are provided in the table below.
 
 The current version of DRAGONS has been tested with Python 3.10.  At the time
 of this writing, Miniforge installs Python 3.10 by default.  (Other version
-of Python an subsequently be installed.)
+of Python can subsequently be installed.)
 
-To install, run the installer that you have downloaded
-Type the following in a terminal, replacing the ``.sh`` file name to the name
-of the file you have downloaded.  The ``/bin/bash -l`` line is not needed if
-you are already using bash.
+To install, run the installer that you have downloaded.
+Type the following in a terminal, replacing the ``.sh`` file name with the name
+of the file you have downloaded.
 
 ::
 
     $ /bin/bash Miniforge3-MacOSX-x86_64.sh
 
 (``$`` indicates the terminal prompt.)
 
-.. note::  For the arm64 Macs, it will note that the architecture does not
+.. note::  For the arm64 Macs, it will tell you that the architecture does not
            match.  That's okay, type `yes` to accept.
 
-At "Do you wish to update your shell profile to automatically initialize conda?",
-answer "no".   The script sometimes put the "conda init" information in the
+At ``"Do you wish to update your shell profile to automatically initialize conda?"``,
+answer `no`.   The script sometimes put the "conda init" information in the
 wrong shell file (observed on Mac).  To avoid confusion do the initialization
 manually::
 
@@ -108,20 +108,20 @@ Make sure that ``~/miniforge3/bin/conda`` is in your ``PATH`` by doing::
 
     $ which conda
 
-It should show a path with `miniforge3`, not `anaconda`.
+It should show a path with ``miniforge3``, not ``anaconda``.
 
 .. note:: If you had a previous installation of Anaconda, you might need to
           find the Anaconda's "conda initialize" block and comment it out.
           Look in files like .bash_profile, .bashrc, .zshrc.
 
 The `conda init` command should have added conda configurations to the
-``~/.bash_profile`` for you (or .bashrc, .zshrc).  If ``conda`` is not found,
+``~/.bash_profile`` for you (or ``.bashrc``, ``.zshrc``).  If ``conda`` is not found,
 try::
 
     $ source ~/.bash_profile
 
-The code Miniforge adds to the .bash_profile will automatically activate
-miniforge.  To activate or deactivate Anaconda manually::
+The code Miniforge adds to the ``.bash_profile`` will automatically activate
+Miniforge.  To activate or deactivate Miniforge manually::
 
     $ conda activate
     $ conda deactivate
@@ -142,12 +142,11 @@ that we will need.
     $ conda config --add channels conda-forge
     $ conda config --add channels http://astroconda.gemini.edu/public
 
-The content of the `~/.condarc` file should look like this::
+The content of the `~/.condarc` file should look like this (the order matters)::
 
    channels:
      - http://astroconda.gemini.edu/public
      - conda-forge
-     - defaults
 
 The next step is to create a virtual environment and install the DRAGONS
 software and its dependencies in it.  The name of the environment can be
@@ -203,7 +202,7 @@ on your preferences.  The path and name of the calibration database can be
 anything, as long at the path exists.  The "get" means that DRAGONS will get
 calibrations from that database.  The "store" option can be added after the
 "get" to have DRAGONS automatically add new processed calibrations to the
-database.  See any of the tutorials to see the calibration manager in action.
+database.  See any of the tutorials to learn how to use the calibration manager.
 
 On a new installation, you will need to configure ``ds9`` buffer
 configurations::
@@ -244,7 +243,7 @@ are compiled and loaded::
 
     $ reduce --help
 
-This will print the reduce help to the screen.
+This will print the ``reduce`` help to the screen.
 
 If you have Gemini FITS files available, you can test that DRAGONS
 is functioning as expected as follow (replace the file name with the name