Merge branch 'dev' into 1074-target-detail-page-could-automatically-d…

…isplay-what-constellation-a-target-is-in

docs/api/tom_observations/models.rst

@@ -1,5 +1,16 @@
 Models
 ======
 
+
+******************************************
+Observation Records vs. Observation Groups
+******************************************
+In the TOM Toolkit, `Observation Records` represent the details of an individual observation as submitted to the
+observatory. This is what will be updated with a new status as the observation is completed.
+
+`Observation Groups` are any arbitrary collection of observations that might be related to each other in some way.
+This might be everything observed on a certain night, everything observed by a single user, or some other science-based
+grouping.
+
 .. automodule:: tom_observations.models
     :members:

docs/api/tom_targets/groups.rst

@@ -1,5 +1,10 @@
-Group Management
-================
+Target Lists
+============
+
+Target lists are a way for you to group your ``Targets`` together. This can be for any number of purposes, including
+creating an observing list, grouping similar targets for further analysis, or simply for organizational purposes.
+
+You can group ``Targets`` through the API or from the 'Target Groupings' page in the TOM.
 
 .. automodule:: tom_targets.groups
     :members:

docs/common/customsettings.rst

@@ -86,6 +86,8 @@ documentation on `Adding Custom Fields to
 Targets </targets/target_fields>`__ for an explanation of how to use
 this feature.
 
+.. _custom_facility_settings:
+
 `FACILITIES <#facilities>`__
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/common/permissions.rst

@@ -2,14 +2,28 @@ The Permissions System
 ======================
 
 The permissions system is built on top of
-`django-guardian <https://django-guardian.readthedocs.io/en/stable/>`_. It has been
+`django-guardian <https://django-guardian.readthedocs.io/en/stable/>`__. It has been
 kept as simple as possible, but TOM developers may extend the capabilities if
 needed.
 
 The TOM Toolkit provides a permissions system that can be used in two different modes. The mode is controlled by the
 ``TARGET_PERMISSIONS_ONLY`` boolean in ``settings.py``.
 
 
+`AnonymousUser`
+---------------
+
+When you first establish your TOM, ``django-guardian`` will create an ``AnonymousUser`` as the default user for the
+TOM. ``AnonymousUser`` is a special user that is used to represent users who are not logged in and only has permission
+to see targets that are associated with the ``public`` group by default. This user is important for establishing what
+permissions are available to users who are not logged in and should not be removed. You can modify the permissions of
+``AnonymousUser`` by using the Django admin interface or the methods described below.
+
+*Note:* This ``AnonymousUser`` is not the same as the ``AnonymousUser`` object that is part of
+`Django's authentication system. <https://docs.djangoproject.com/en/5.1/ref/contrib/auth/#anonymoususer-object>`__
+
+
+
 First Mode -- Permissions on Targets and Observation Records
 ------------------------------------------------------------
 
@@ -25,18 +39,13 @@ button found at the top of the groups table:
 
 .. image:: /_static/permissions_doc/addgroup.png
 
-![](/_static/permissions_doc/addgroup.png)
-
 Modifying a group will allow you to change it's name and add/remove users.
 
 When a user adds or modifies a target, they are able to choose the groups to
 assign to the target:
 
 .. image:: /_static/permissions_doc/targetgroups.png
 
-![](/_static/permissions_doc/targetgroups.png)
-
-
 By default the target will be assigned to all groups the user belongs to.
 
 There is a special group, "Public". By default, all users belong to the Public

docs/introduction/faqs.rst

@@ -40,8 +40,8 @@ I try to observe a target with LCO but get an error.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You might not have added your LCO api key to your settings file under
-the ``FACILITIES`` settings. See :doc:`Custom
-Settings </common/customsettings#facilities>` for more
+the ``FACILITIES`` settings. See :ref:`Custom
+Settings <custom_facility_settings>` for more
 details.
 
 How do I create a super user (PI)?
@@ -103,12 +103,15 @@ This will make the contents of ``newpage.html`` available under the path
 Who is AnonymousUser?
 ~~~~~~~~~~~~~~~~~~~~~
 
-AnonymousUser is a special profile that django-guardian, our permissions
+`AnonymousUser` is a special profile that django-guardian, our permissions
 library, creates automatically. AnonymousUser represents an
 unauthenticated user. The user has no first name, last name, or
 password, and allows unauthenticated users to view unprotected pages
-within your TOM. You can choose to delete the user if you don’t want any
-pages to be visible without logging in.
+within your TOM. Do not delete this user, as then an unauthorized user will not
+have access to the login page.
+
+*Note:* This ``AnonymousUser`` is not the same as the ``AnonymousUser`` object that is part of
+`Django's authentication system. <https://docs.djangoproject.com/en/5.1/ref/contrib/auth/#anonymoususer-object>`_
 
 How can I display an error message when authentication to an external facility fails?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/introduction/manual_installation.rst

@@ -11,16 +11,9 @@ Manually Installing the TOM Toolkit and Django
 
 If you prefer to build your system manually, here's how.
 
-Firstly, the TOM toolkit requires you to have Python >= 3.7 installed
+Firstly, the TOM toolkit requires you to have Python >= 3.8.1, < 3.12 installed
 on your machine.
 
-If you are using Python 3.6 and cannot upgrade to 3.7, install the
-``dataclasses`` backport:
-
-::
-
-   pip install dataclasses
-
 We recommend using a `virtual
 environment <https://docs.python.org/3/tutorial/venv.html>`__ for your
 project. This will keep your TOM python packages separate from your
@@ -82,7 +75,8 @@ that it looks like this:
 
 
 Now you can run the ``tom_setup`` app.  It contains a script that will
-bootstrap a new TOM in your current project. Run it like this:
+bootstrap a new TOM in your current project. First return to the main folder that contains ``manage.py`` and run
+``tom_setup`` like this:
 
 ::
 

docs/observing/index.rst

@@ -9,6 +9,7 @@ Observing Facilities and Observations
   ../common/scripts
   strategies
   observation_module
+  ../api/tom_observations/models
   ../api/tom_observations/facilities
   ../api/tom_observations/views
 
@@ -25,6 +26,8 @@ the result of prior observations, as well as how to leverage observing templates
 :doc:`Building a TOM Observation Facility Module <observation_module>` - Learn to build a module which will
 allow your TOM to submit observation requests to observatories.
 
+:doc:`Observation Models <../api/tom_observations/models>` - Learn about the models used to store observation data.
+
 :doc:`Facility Modules <../api/tom_observations/facilities>` - Take a look at the supported facilities.
 
 :doc:`Observation Views <../api/tom_observations/views>` - Familiarize yourself with the available Observation Views.

docs/targets/index.rst

@@ -13,7 +13,9 @@ Targets
 
 
 The ``Target``, along with the associated ``TargetList``, ``TargetExtra``, and ``TargetName``, are the core models of the 
-TOM Toolkit. The ``Target`` defines the concept of an astronomical target.
+TOM Toolkit. The ``Target`` defines the concept of an astronomical target through a number of parameters. This
+object is then used throughout the TOM to reference all the information a user or app needs to know about a target.
+More information on Targets can be found using the following pages:
 
 :doc:`Adding Custom Target Fields <target_fields>` - Learn how to add custom fields to your TOM Targets if the
 defaults do not suffice.
@@ -25,4 +27,4 @@ options are needed.
 
 :doc:`Target Views <../api/tom_targets/views>` - Familiarize yourself with the available Target Views.
 
-:doc:`Target Groups <../api/tom_targets/groups>` - Check out the functions for operating on Target Groups.
+:doc:`Target Lists <../api/tom_targets/groups>` - Check out the functions for operating on Target Lists/Target Groups.

docs/targets/target_fields.rst

@@ -260,6 +260,10 @@ the built in fields whenever possible.
 
 Enabling extra fields
 ~~~~~~~~~~~~~~~~~~~~~
+``EXTRA_FIELDS`` can be implemented in two different ways. If a user wants to add a unique extra field to a individual
+target, that can be done by either adding a "Tag" to a target through the UI, or by adding a single extra field
+programmatically. If the user instead wants a common extra field to be available for all targets, they can follow these
+instructions:
 
 To start, find the ``EXTRA_FIELDS`` definition in your ``settings.py``:
 

tom_observations/facilities/lco.py

@@ -1100,9 +1100,11 @@ def layout(self):
 class LCOFacility(OCSFacility):
     """
     The ``LCOFacility`` is the interface to the Las Cumbres Observatory Observation Portal. For information regarding
-    LCO observing and the available parameters, please see https://observe.lco.global/help/.
+    LCO observing and the available parameters, please see the Getting Started Guide at
+    https://lco.global/documents/2505/GettingStartedontheLCONetwork.latest.pdf.
     """
     name = 'LCO'
+    link = 'https://lco.global/documents/2505/GettingStartedontheLCONetwork.latest.pdf'
     observation_forms = {
         'IMAGING': LCOImagingObservationForm,
         'MUSCAT_IMAGING': LCOMuscatImagingObservationForm,

tom_observations/templates/tom_observations/observation_form.html

@@ -8,6 +8,9 @@
 {% block content %}
 {{ form|as_crispy_errors }}
 <h3>Submit an observation to {{ form.facility.value }} for <a href="{% url 'targets:detail' pk=target.id %}">{{target.name}}</a></h3>
+{% if facility_link %}
+    Please see the <a href="{{ facility_link }}" target="_blank">facility documentation</a> for more information.
+{% endif %}
 {% if missing_configurations %}
     <div class="alert alert-danger">Some {{ form.facility.value }} Facility settings ({{ missing_configurations }}) are not configured.</div>
 {% endif %}
@@ -17,6 +20,8 @@ <h3>Submit an observation to {{ form.facility.value }} for <a href="{% url 'targ
     {% observation_plan target form.facility.value %}
     </div>
 </div>
+{% else %}
+<hr>
 {% endif %}
 <div class="row">
     <div class="col-md-6">

tom_observations/views.py

@@ -228,6 +228,8 @@ def get_context_data(self, **kwargs):
         facility_context = facility.get_facility_context_data(target=target)
         context.update(facility_context)
 
+        context['facility_link'] = getattr(facility, 'link', '')
+
         try:
             context['missing_configurations'] = ", ".join(facility.facility_settings.get_unconfigured_settings())
         except AttributeError: