DOC: fix remaining sphinx issues

docs/dal/index.rst

@@ -105,11 +105,11 @@ return more than 10000 rows”).
 
 This information is contained in the data structure
 :py:class:`~pyvo.io.vosi.endpoint.CapabilitiesFile` available through
-:py:attr:`~pyvo.dal.CapabilityMixin.capabilities`.
+the ``pyvo.dal.vosi.CapabilityMixin.capabilities`` attribute.
 
 Exceptions
 ----------
-See :py:mod:`pyvo.dal.exceptions`.
+See the ``pyvo.dal.exceptions`` module.
 
 .. _pyvo-services:
 
@@ -622,7 +622,7 @@ Get the current job phase:
     EXECUTING
 
 Maximum run time in seconds is available and can be changed with
-:py:attr:`~pyvo.dal.tap.AsyncTAPJob.execution_duration`
+:py:attr:`~pyvo.dal.AsyncTAPJob.execution_duration`
 
 .. doctest-remote-data::
 
@@ -639,18 +639,18 @@ Obtaining the job url, which is needed to reconstruct the job at a later point:
 
 Besides ``run`` there are also several other job control methods:
 
-* :py:meth:`~pyvo.dal.tap.AsyncTAPJob.abort`
-* :py:meth:`~pyvo.dal.tap.AsyncTAPJob.delete`
-* :py:meth:`~pyvo.dal.tap.AsyncTAPJob.wait`
+* :py:meth:`~pyvo.dal.AsyncTAPJob.abort`
+* :py:meth:`~pyvo.dal.AsyncTAPJob.delete`
+* :py:meth:`~pyvo.dal.AsyncTAPJob.wait`
 
 .. note::
     Usually the service deletes the job after a certain time, but it is a good
     practice to delete it manually when done.
 
     The destruction time can be obtained and changed with
-    :py:attr:`~pyvo.dal.tap.AsyncTAPJob.destruction`
+    :py:attr:`~pyvo.dal.AsyncTAPJob.destruction`
 
-Also, :py:class:`pyvo.dal.tap.AsyncTAPJob` works as a context manager which
+Also, :py:class:`pyvo.dal.AsyncTAPJob` works as a context manager which
 takes care of this automatically:
 
 .. doctest-remote-data::
@@ -667,9 +667,9 @@ Check for errors in the job execution:
     >>> job.raise_if_error()
 
 If the execution was successful, the resultset can be obtained using
-:py:meth:`~pyvo.dal.tap.AsyncTAPJob.fetch_result`
+:py:meth:`~pyvo.dal.AsyncTAPJob.fetch_result`
 
-The result url is available under :py:attr:`~pyvo.dal.tap.AsyncTAPJob.result_uri`
+The result url is available under :py:attr:`~pyvo.dal.AsyncTAPJob.result_uri`
 
 .. _pyvo-resultsets:
 

docs/index.rst

@@ -124,8 +124,8 @@ observational datasets through TAP tables), you can write:
     ivo://xcatdb/4xmm/tap
 
 
-Using `pyvo`
-------------
+Using ``pyvo``
+--------------
 
 .. toctree::
    :maxdepth: 1

docs/io/index.rst

@@ -1,6 +1,7 @@
-**************
-IO (`pyvo.io`)
-**************
+****************
+IO (``pyvo.io``)
+****************
+
 This module contains submodules which handle datastructures related to the
 virtual observatory.
 

docs/io/uws.rst

@@ -1,6 +1,6 @@
-*******************
-UWS (`pyvo.io.uws`)
-*******************
+*********************
+UWS (``pyvo.io.uws``)
+*********************
 
 Reference/API
 =============

docs/io/vosi.rst

@@ -1,6 +1,6 @@
-*********************
-VOSI (`pyvo.io.vosi`)
-*********************
+***********************
+VOSI (``pyvo.io.vosi``)
+***********************
 
 Reference/API
 =============

docs/nitpick-exceptions

@@ -2,7 +2,12 @@
 py:class pyvo.dal.vosi.AvailabilityMixin
 
 # Non-public API classes. We should probably remove references to them altogether
-py:class pyvo.io.uws.tree.Jobs
+py:obj pyvo.io.uws.tree.Jobs
 py:class pyvo.dal.vosi.CapabilityMixin
 py:class pyvo.dal.vosi.EndpointMixin
 py:class pyvo.dal.adhoc.AxisParamMixin
+py:class pyvo.dam.obscore.ObsCoreMetadata
+py:obj pyvo.registry.regtap.Interface
+# There is no public API docs for this, yet it's useful to leave the reference in
+py:obj pyvo.io.vosi.exceptions
+py:class pyvo.dal.exceptions.PyvoUserWarning

docs/registry/index.rst

@@ -207,8 +207,8 @@ the first conesearch it finds.
 However some providers provide multiple services of the same type
 -- for example in VizieR you'll find one conesearch per table.
 In this case, you can inspect the available services with
-`~pyvo.registry.RegistryResource.list_services`. Then, you can refine your
-instructions to `~pyvo.registry.RegistryResource.get_service` with a keyword
+`~pyvo.registry.regtap.RegistryResource.list_services`. Then, you can refine your
+instructions to `~pyvo.registry.regtap.RegistryResource.get_service` with a keyword
 constraint on the description ``get_service(service_type='conesearch', keyword='sncat')``.
 
 .. doctest-remote-data::

docs/utils/index.rst

@@ -1,8 +1,8 @@
 .. _pyvo-utils:
 
-*************************
-PyVO utils (`pyvo.utils`)
-*************************
+***************************
+PyVO utils (``pyvo.utils``)
+***************************
 
 
 This module contains utilities and base classes intended for internal use

docs/utils/prototypes.rst

@@ -87,6 +87,7 @@ Reference/API
 =============
 
 .. automodapi:: pyvo.utils.prototype
+.. automodapi:: pyvo.utils.protofeature
 
 
 Existing Prototypes

pyvo/dal/adhoc.py

@@ -494,7 +494,7 @@ def getrecord(self, index):
         return a representation of a datalink result record that follows
         dictionary semantics. The keys of the dictionary are those returned by
         this instance's fieldnames attribute. The returned record has the
-        additional function :py:meth:`~pyvo.dal.DALResults.getdataset`
+        additional function ``getdataset``
 
         Parameters
         ----------
@@ -515,7 +515,7 @@ def getrecord(self, index):
 
         See Also
         --------
-        Record
+        pyvo.dal.Record
         """
         return DatalinkRecord(self, index, session=self._session)
 
@@ -635,7 +635,7 @@ class SodaRecordMixin:
     """
     Mixin for soda functionality for record classes.
     If used, it's result class must have
-    `pyvo.dal.datalink.AdhocServiceResultsMixin` mixed in.
+    `pyvo.dal.adhoc.AdhocServiceResultsMixin` mixed in.
     """
 
     def _get_soda_resource(self):

pyvo/dal/query.py

@@ -324,7 +324,7 @@ def __init__(self, votable, *, url=None, session=None):
 
         See Also
         --------
-        DALFormatError
+        pyvo.dal.DALFormatError
         """
         self._votable = votable
 

pyvo/dal/sia2.py

@@ -4,7 +4,7 @@
 
 A Simple Image Access v2 (SIA2) service allows a client to search for
 images based on a number of criteria/parameters. The results are
-represented in `pyvo.dam.obscore.ObsCoreMetadata` format.
+represented in ``pyvo.dam.ObsCoreMetadata`` format.
 
 The ``SIA2Service`` class can represent a specific service available at a URL
 endpoint.
@@ -45,7 +45,7 @@
     the energy interval(s) to be searched for data.
 time : single or list of `~astropy.time.Time` or compatible strings
     the time interval(s) to be searched for data.
-pol : single or list of str from `pyvo.dam.obscore.POLARIZATION_STATES`
+pol : single or list of str from ``pyvo.dam.obscore.POLARIZATION_STATES``
     the polarization state(s) to be searched for data.
 field_of_view : single or list of tuples
     angle units (default arcsec)
@@ -76,7 +76,7 @@
 data_type : 'image'|'cube'
     specifies the type of the data
 calib_level : single or list from enum
-    `pyvo.dam.obscore.CALIBRATION_LEVELS`
+    ``pyvo.dam.obscore.CALIBRATION_LEVELS``
     specifies the calibration level of the data. Can be a single value
     or a list of values
 target_name : single or list of str
@@ -1078,7 +1078,7 @@ def pol_xel(self):
         """
         Number of different polarization states present in the data. The
         default value is 0, indicating that polarization was not explicitly
-        observed. Corresponding values are stored in the `pol` property
+        observed. Corresponding values are stored in the ``pol`` property
         """
         return self.get('pol_xel')
 

pyvo/dal/tap.py

@@ -400,7 +400,7 @@ def get_job(self, job_id):
 
         Returns
         -------
-        `~pyvo.io.vosi.endpoint.JobSummary` corresponding to the job ID
+        `~pyvo.io.uws.tree.JobSummary` corresponding to the job ID
         """
         response = self._session.get(
             self.baseurl + '/async/' + job_id,
@@ -433,7 +433,7 @@ def get_job_list(self, *, phases=None, after=None, last=None,
 
         Returns
         -------
-        list of `~pyvo.io.vosi.endpoint.JobSummary`
+        list of `~pyvo.io.uws.tree.JobSummary`
         """
 
         params = {'PHASE': phases, 'LAST': last}

pyvo/io/uws/endpoint.py

@@ -75,7 +75,7 @@ def parse_job(
 
     Returns
     -------
-    `~pyvo.io.vosi.endpoint.JobFile` object
+    `~pyvo.io.uws.endpoint.JobFile` object
 
     See also
     --------

pyvo/registry/regtap.py

@@ -170,7 +170,7 @@ def search(*constraints: rtcons.Constraint,
 
     The function accepts query constraints either as Constraint objects
     passed in as positional arguments or as their associated keywords.
-    For what constraints are available, see ref:`registry-basic-interface`.
+    For what constraints are available, see :ref:`registry-basic-interface`.
 
 
     The values of keyword arguments may be tuples or lists when the associated
@@ -181,7 +181,7 @@ def search(*constraints: rtcons.Constraint,
 
     Parameters
     ----------
-    *constraints : `rtcons.Constraint` instances
+    *constraints : `~pyvo.registry.Constraint` instances
         The constraints (keywords to match, positions to cover, ...)
         that the returned records need to satisfy.
         The accepted constraints are:
@@ -234,12 +234,9 @@ def search(*constraints: rtcons.Constraint,
 
     Returns
     -------
-    RegistryResults
+    ~pyvo.registry.regtap.RegistryResults`
        a container holding a table of matching resource (e.g. services)
 
-    See Also
-    --------
-    RegistryResults
     """
     service = get_RegTAP_service()
     query = RegistryQuery(
@@ -586,9 +583,6 @@ def res_description(self):
         """
         the textual description of the resource.
 
-        See Also
-        --------
-        SimpleResource.describe
         """
         return self.get("res_description", decode=True)
 
@@ -890,7 +884,8 @@ def service(self):
         return self._service
 
     def list_services(self, service_type: str = None):
-        """List the services available for this registry record.
+        """
+        List the services available for this registry record.
 
         Parameters
         ----------
@@ -910,6 +905,7 @@ def list_services(self, service_type: str = None):
         See Also
         --------
         get_service : when there is only one service of a specific service type.
+
         """
         if service_type is not None:
             service_type = expand_stdid(rtcons.SERVICE_TYPE_MAP.get(service_type, service_type))

pyvo/registry/rtcons.py

@@ -179,7 +179,7 @@ def get_search_condition(self, service):
 
         Parameters
         ----------
-        service : `dal.tap.TAPService`
+        service : `~pyvo.dal.TAPService`
             The RegTAP service the query is supposed to be run on
             (that is relevant because we adapt to the features available
             on given services).
@@ -885,7 +885,7 @@ def build_regtap_query(constraints, service):
         will become part of a conjunction (i.e., all of them have
         to be satisfied for a record to match).
 
-    service : `~pyvo.dal.tap.TAPService`
+    service : `~pyvo.dal.TAPService`
         The RegTAP service the query is supposed to be run on
         (that is relevant because we adapt to the features available
         on given services).