BUG: fixing referencing syntax

bsipocz · bsipocz · commit 3bfef66e86e6 · 2025-06-16T15:29:32.000-07:00
diff --git a/docs/mivot/annoter.rst b/docs/mivot/annoter.rst
@@ -1,3 +1,5 @@
+.. _mivot-annoter:
+
 ******************************************************
 MIVOT (``pyvo.mivot``): Annotation Writer - Public API
 ******************************************************
@@ -11,7 +13,7 @@ Mango objects are made of a property container, a description of the data origin
 on other Mango objects (not implemented yet).
 
 In this current implementation, only 3 properties are supported (Epoch position, photometry, and color)
-in addition to the data origin that can be added as literal values (not connected with table data). 
+in addition to the data origin that can be added as literal values (not connected with table data).
 
 The pseudo codes below show the way to use this API.
 
@@ -27,26 +29,26 @@ The ``dmid`` optional parameter gives the column (ID or name) to be used as iden
 The builder is then ready to get the properties to add to the Mango object.
 
  .. code-block:: python
- 
+
      builder.add_mango_magnitude(photcal_id=photcal_id, mapping=mapping, semantics=semantics)
      builder.add_mango_magnitude(photcal_id=other_photcal_id, mapping=other_mapping, semantics=other_semantics)
      builder.add_mango_color(filter_ids=filter_ids, mapping=mapping, semantics=semantics)
      builder.add_mango_epoch_position(frames=frames, mapping=mapping, semantics=semantics)
 
-We can now add the description of the data origin. 
+We can now add the description of the data origin.
 
  .. code-block:: python
- 
+
      builder.add_query_origin(mapping)
- 
+
 - The order in which the components are added does not matter.
 - The details of the parameters are described below.
 
 Now the MIVOT block can be completed and inserted into the VOtable.
 
 
  .. code-block:: python
- 
+
     builder.pack_into_votable()
     votable.to_xml("MY/ANNOTATED/VOTABLE")
 
@@ -61,37 +63,37 @@ The lists of supported roles are given in the :py:mod:`pyvo.mivot.glossary`.
 The 3 functions adding properties have all 3 arguments
 
 - ``filter/frame``: Map of the coordinate systems or photometric calibrations that apply to the property.
-  All values specified here are considered literal. 
+  All values specified here are considered literal.
   The corresponding Mivot instances are placed in the GLOBALS block.
-  
+
   - **Photometric filter**: must be given as a filter profile service identifier (filter id followed with the photometric system)
-   
+
     - Identifiers can be found on  the SVO `page <http://svo2.cab.inta-csic.es/theory/fps/>`_
-      (example: ``GAIA/GAIA3.Grp/AB``) 
-    - The FPS service returns a full calibration instance, which is then split into a filter object  
+      (example: ``GAIA/GAIA3.Grp/AB``)
+    - The FPS service returns a full calibration instance, which is then split into a filter object
       and a calibration object that refers to that filter.
     - Each one of these components has its own ``dmid`` generated by the API. ``dmid`` can be used to reference them.
-      Example for filter ``GAIA/GAIA3.Grp/AB``:  
-       
+      Example for filter ``GAIA/GAIA3.Grp/AB``:
+
       - photometric calibration identifer: ``dmid="_photcal_GAIA_GAIA3_Grvs_AB"``
-      - filter identifier ``dmid="_filter_GAIA_GAIA3_Grvs_AB"``   
-  
+      - filter identifier ``dmid="_filter_GAIA_GAIA3_Grvs_AB"``
+
   - **Coordinate systems**: Can be given either by ``dmid`` or by parameters
-    (see `pyvo.mivot.writer.InstancesFromModels.add_simple_space_frame` 
+    (see `pyvo.mivot.writer.InstancesFromModels.add_simple_space_frame`
     and `pyvo.mivot.writer.InstancesFromModels.add_simple_time_frame`).
 
-    - by ``dmid``: Identifiers are generated by the API when a frame is added in the GLOBALS. 
+    - by ``dmid``: Identifiers are generated by the API when a frame is added in the GLOBALS.
       (example ``{"dmid": "_spaceframe_spaceRefFrame_equinox_refPosition"}``)
     - by parameters: The mapping parameters are given as dictionaries as for the mapping  (see below)
       (example ``{"spaceRefFrame": "ICRS", "refPosition": 'BARYCENTER'}``)
 
-- ``Mapping``: Mapping of the table data to the property attributes. 
+- ``Mapping``: Mapping of the table data to the property attributes.
   The fine structure of these dictionaries is specific to each mapped class,
   but all follow the same pattern.
   Values specified as strings are considered to be column identifiers,
   unless the string starts with a '*'. In this case, the stripped string is taken as the literal value.
-  Other value types (numeric or boolean) are all considered as literals. 
-  
+  Other value types (numeric or boolean) are all considered as literals.
+
   +-------------+---------------------------------+
   | **value**   | **attribute value**             |
   +=============+=================================+
@@ -107,7 +109,7 @@ The 3 functions adding properties have all 3 arguments
   +-------------+---------------------------------+
 
 - ``semantics``: Semantic tags (text + vocabulary entry) that apply to the property.
-  
+
   +-------------+---------------------------------------------------------+
   + **key**     | **value**                                               +
   +=============+=========================================================+
@@ -118,7 +120,7 @@ The 3 functions adding properties have all 3 arguments
   + label       + vocabulary term to which the property refers            +
   +-------------+---------------------------------------------------------+
 
-  All ``semantics`` fields are considered literal values. 
+  All ``semantics`` fields are considered literal values.
 
 Add Query origin
 ----------------
@@ -127,7 +129,7 @@ Add the Mango ``QueryOrigin`` instance to the current ``MangoObject``.
 
 .. figure:: _images/mangoDataOrigin.png
    :width: 500
- 
+
    DataOrigin package of Mango.
 
 
@@ -142,7 +144,7 @@ of the MangoObject. It is always identified with ``dmid="_origin"``
 The detail of the ``mapping`` parameter is given in the `pyvo.mivot.writer.InstancesFromModels.add_query_origin` documentation
 
 The ``QueryOrigin`` object can be automatically built from the INFO tags of the VOtable. The success of this operation depends
-on the way INFO tags are populated. 
+on the way INFO tags are populated.
 
 The method below, analyzes the INFO tags and insert the resulting query origin into the annotations.
 
@@ -155,20 +157,20 @@ The method below, analyzes the INFO tags and insert the resulting query origin i
 - INFO tags of the header of the first resource are analyzed to set the ``DataOrigin`` objects.
 - The automatic mapping does not work for VOtable joining several tables yet.
 
-   
+
 Add Properties
 --------------
 
 The main purpose of the ``MangoObject`` is to collect various properties contained in the data row,
 although synthetic properties (literal value only) can be added as well.
 
-- The properties are stored in a container named ``propertyDock``. 
-- During he annotation process, properties are added one by one by specific methods. 
+- The properties are stored in a container named ``propertyDock``.
+- During he annotation process, properties are added one by one by specific methods.
 
 .. figure:: _images/mangoProperties.png
    :width: 500
-   
-   
+
+
    Properties supported by Mango.
 
 Add EpochPosition
@@ -178,8 +180,8 @@ The ``EpochPosition`` property describes the astrometry of a moving source.
 
 .. figure:: _images/mangoEpochPosition.png
    :width: 500
-   
-   
+
+
    EpochPosition components of Mango.
 
 It handles six parameters (position, proper motion, parallax and radial velocity) valid at a given epoch
@@ -189,7 +191,7 @@ It handles six parameters (position, proper motion, parallax and radial velocity
 
     builder.add_epoch_position(frames, mapping, semantics)
 
-The detail of the parameters is given with the description of the 
+The detail of the parameters is given with the description of the
 :py:meth:`pyvo.mivot.writer.InstancesFromModels.add_mango_epoch_position` method.
 
 The first parameter (``frames``) specifies both space and time frames.
@@ -226,7 +228,7 @@ The ``Brightness`` binds a flux or a magnitude with an error and a photometric c
 
     builder.add_mango_brightness(photcal_id, mapping, semantics)
 
-The detail of the parameters is given with the 
+The detail of the parameters is given with the
 :py:meth:`pyvo.mivot.writer.InstancesFromModels.add_mango_brightness` docstring.
 
 Add Color
@@ -238,7 +240,7 @@ The ``Color`` binds to a Color index or an hardness ratio value with an error an
 
     builder.add_mango_color(filter_ids, mapping, semantics)
 
-The detail of the parameters is given with the 
+The detail of the parameters is given with the
 :py:meth:`pyvo.mivot.writer.InstancesFromModels.add_mango_color` docstring.
 
 
diff --git a/docs/mivot/example.rst b/docs/mivot/example.rst
@@ -7,7 +7,7 @@ Photometric properties readout
 
 This example is based on VOTables provided by the ``XTapDB`` service.
 This service exposes the slim `4XMM dr14 catalogue <http://xmmssc.irap.omp.eu/>`_.
-It  is able to map query responses on the fly to the MANGO data model. 
+It  is able to map query responses on the fly to the MANGO data model.
 The annotation process only annotates the columns that are selected by the query.
 
 The following properties are supported:
@@ -23,32 +23,32 @@ to tell the server to annotate the queried data.
 (*Please read the comment inside the code snippet carefully to fully understand the process*)
 
  .. code-block:: python
- 
+
     import pytest
     from pyvo.utils import activate_features
     from pyvo.dal import TAPService
     from pyvo.mivot.utils.xml_utils import XmlUtils
     from pyvo.mivot.utils.dict_utils import DictUtils
     from pyvo.mivot.viewer.mivot_viewer import MivotViewer
- 
+
     # Enable MIVOT-specific features in the pyvo library
     activate_features("MIVOT")
- 
+
     service = TAPService('https://xcatdb.unistra.fr/xtapdb')
     result = service.run_sync(
         """
-        SELECT TOP 5 * FROM "public".mergedentry 
+        SELECT TOP 5 * FROM "public".mergedentry
         """,
         format="application/x-votable+xml;content=mivot"
         )
- 	
+
     # The MIVOT viewer generates the model view of the data
-    m_viewer = MivotViewer(result, resolve_ref=True)   
-     	
+    m_viewer = MivotViewer(result, resolve_ref=True)
+
     # Print out the Mivot annotations read out of the VOtable
     # This statement is just for a pedagogic purpose (access to a private attribute)
     XmlUtils.pretty_print(m_viewer._mapping_block)
-    
+
 
 In this first step we just queried the service and we built the object that will process the Mivot annotations.
 The Mivot block printing output is too long to be listed here. However, the screenshot below shows its shallow structure.
@@ -61,13 +61,13 @@ The Mivot block printing output is too long to be listed here. However, the scre
   the detection flags and the photometric calibrations.
 - The TEMPLATES section contains the objects to which table data is mapped. In this example, there is one
   ``MangoObject`` instance which holds all the mapped properties.
-   
+
 At instantiation time, the viewer reads the first data row, which must exist,
-in order to construct a Python object that reflects the mapped model. 
+in order to construct a Python object that reflects the mapped model.
 
  .. code-block:: python
-  
-    # Build a Python object matching the TEMPLATES content and 
+
+    # Build a Python object matching the TEMPLATES content and
     # which leaves are set with the values of the first row
     mango_object = m_viewer.dm_instance
 
@@ -107,12 +107,12 @@ Now, we can iterate through the table data and retrieve an updated Mivot instanc
     ...
 
 The same code can easily be connected with matplotlib to plot SEDs as shown below (code not provided).
-  
+
 
 .. image:: _images/xtapdbSED.png
    :width: 500
    :alt: XMM SED
-   
+
 It is to noted that the current table row keeps available through the Mivot viewer.
 
  .. code-block:: python
@@ -133,23 +133,23 @@ EpochPosition property readout
 ==============================
 
 This example is based on a VOtable resulting on a Vizier cone search.
-This service maps the data to  the ``EpochPosition`` MANGO property, 
+This service maps the data to  the ``EpochPosition`` MANGO property,
 which models a full source's  astrometry at a given date.
 
 
 .. warning::
    At the time of writing, Vizier only mapped positions and proper motions (when  available),
    and the definitive epoch class had not been adopted.
    Therefore, this implementation may differ a little bit from the standard model.
-   
+
    Vizier does not wrap the source properties in a MANGO object,
-   but rather lists them in the Mivot *TEMPLATES*. 
+   but rather lists them in the Mivot *TEMPLATES*.
    The annotation reader must support both designs.
 
 In the first step below, we run a standard cone search query by using the standard PyVO API.
 
  .. code-block:: python
- 
+
     import pytest
     import astropy.units as u
     from astropy.coordinates import SkyCoord
@@ -162,7 +162,7 @@ In the first step below, we run a standard cone search query by using the standa
 
     # Enable MIVOT-specific features in the pyvo library
     activate_features("MIVOT")
-    
+
     scs_srv = SCSService("https://vizier.cds.unistra.fr/viz-bin/conesearch/V1.5/I/239/hip_main")
 
     query_result = scs_srv.search(
@@ -175,8 +175,8 @@ In the first step below, we run a standard cone search query by using the standa
 Once the query is finished, we can get a reference to the object that will process the Mivot annotations.
 
  .. code-block:: python
-  
-    # Build a Python object matching the TEMPLATES content and 
+
+    # Build a Python object matching the TEMPLATES content and
     # which leaves are set with the values of the first row
     mango_property = m_viewer.dm_instance
 
@@ -188,7 +188,7 @@ The annotations are consumed by this dynamic Python object which leaves are set
 You can explore the structure of this object by using standard object paths or by browsing the dictionary shown below.
 
  .. code-block:: json
- 
+
 	{
 	  "dmtype": "mango:EpochPosition",
 	  "longitude": {
@@ -234,14 +234,14 @@ You can explore the structure of this object by using standard object paths or b
 	      }
 	    }
 	  }
-	}   
+	}
+
 
- 
  The reader can transform ``EpochPosition`` instances into ``SkyCoord`` instances.
  These can then be used for further scientific processing.
-   
+
  .. code-block:: python
- 
+
     while m_viewer.next_row_view():
        if mango_property.dmtype == "mango:EpochPosition":
            scb = SkyCoordBuilder(mango_property.to_dict())
@@ -251,9 +251,9 @@ You can explore the structure of this object by using standard object paths or b
 .. important::
    Similar to the previous example, this code can be used with any VOTable with data mapped to MANGO.
    It contains no features specific to the Vizier output.
-   
+
    It avoids the need for users to build SkyCoord objects by hand from VOTable fields,
    which is never an easy task.
- 
- 
-The next section provides some tips to use the API documented in the annoter `page <annoter.html>`_.
+
+
+The next section provides some tips to use the API documented in the :ref:`annoter page <mivot-annoter>`.
