Merge pull request #416 from bsipocz/DOC_nitpicky

DOC: Enabling nitpicky docs build

docs/auth/index.rst

@@ -1,10 +1,14 @@
+.. _pyvo-auth:
+
 ******************
 Auth (`pyvo.auth`)
 ******************
+
 This module contains submodules which help handle auth when
 communicating with virtual observatory services.
 
 Reference/API
 =============
 
 .. automodapi:: pyvo.auth
+    :no-inheritance-diagram:

docs/conf.py

@@ -161,3 +161,15 @@
 
     edit_on_github_source_root = ""
     edit_on_github_doc_root = "docs"
+
+
+# -- Enable nitpicky mode - which ensures that all references in the docs resolve ----
+
+nitpicky = True
+# See docs/nitpick-exceptions file for the actual listing.
+nitpick_ignore = []
+for line in open("nitpick-exceptions"):
+    if line.strip() == "" or line.startswith("#"):
+        continue
+    dtype, target = line.split(None, 1)
+    nitpick_ignore.append((dtype, target.strip()))

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.mixin.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
@@ -134,4 +134,5 @@ Using `pyvo`
    registry/index
    io/index
    auth/index
+   utils/index
    utils/prototypes

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

@@ -0,0 +1,13 @@
+# Deprecated API
+py:class pyvo.dal.vosi.AvailabilityMixin
+
+# Non-public API classes. We should probably remove references to them altogether
+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

@@ -42,35 +42,35 @@ This function accepts one or more search constraints, which can be
 either specified using constraint objects as positional arguments or as
 keyword arguments.  The following constraints are available:
 
-* :py:class:`pyvo.registry.Freetext` (``keywords``): one or more
+* :py:class:`~pyvo.registry.Freetext` (``keywords``): one or more
   freetext words, mached in the title, description or subject of the
   resource.
-* :py:class:`pyvo.registry.Servicetype` (``servicetype``): constrain to
+* :py:class:`~pyvo.registry.Servicetype` (``servicetype``): constrain to
   one of tap, ssa, sia, conesearch (or full ivoids for other service
   types).  This is the constraint you want
   to use for service discovery.
-* :py:class:`pyvo.registry.UCD` (``ucd``): constrain by one or more UCD
+* :py:class:`~pyvo.registry.UCD` (``ucd``): constrain by one or more UCD
   patterns; resources match when they serve columns having a matching
   UCD (e.g., ``phot.mag;em.ir.%`` for “any infrared magnitude”).
-* :py:class:`pyvo.registry.Waveband` (``waveband``): one or more terms
+* :py:class:`~pyvo.registry.Waveband` (``waveband``): one or more terms
   from the vocabulary at http://www.ivoa.net/rdf/messenger giving the rough
   spectral location of the resource.
-* :py:class:`pyvo.registry.Author` (``author``): an author (“creator”).
+* :py:class:`~pyvo.registry.Author` (``author``): an author (“creator”).
   This is a single SQL pattern, and given the sloppy practices in the
   VO for how to write author names, you should probably generously use
   wildcards.
-* :py:class:`pyvo.registry.Datamodel` (``datamodel``): one of obscore,
+* :py:class:`~pyvo.registry.Datamodel` (``datamodel``): one of obscore,
   epntap, or regtap: only return TAP services having tables of this
   kind.
-* :py:class:`pyvo.registry.Ivoid` (``ivoid``): exactly match a single
+* :py:class:`~pyvo.registry.Ivoid` (``ivoid``): exactly match a single
   IVOA identifier (that is, in effect, the primary key in the VO).
-* :py:class:`pyvo.registry.Spatial` (``spatial``): match resources
+* :py:class:`~pyvo.registry.Spatial` (``spatial``): match resources
   covering, enclosed or overlapping a certain geometry
   (point, circle, polygon, or MOC). *RegTAP 1.2 Extension*
-* :py:class:`pyvo.registry.Spectral` (``spectral``): match resources
+* :py:class:`~pyvo.registry.Spectral` (``spectral``): match resources
   covering a certain part of the spectrum (usually, but not limited to,
   the electromagnetic spectrum).  *RegTAP 1.2 Extension*
-* :py:class:`pyvo.registry.Temporal` (``temporal``): match resources
+* :py:class:`~pyvo.registry.Temporal` (``temporal``): match resources
   covering a some point or interval in time.  *RegTAP 1.2 Extension*
 
 Multiple constraints are combined conjunctively (”AND”).
@@ -109,7 +109,7 @@ is equivalent to:
 
   >>> resources = registry.search(waveband=["Radio", "Millimeter"])
 
-There is also :py:meth:`pyvo.registry.get_RegTAP_query`, accepting the
+There is also :py:meth:`~pyvo.registry.get_RegTAP_query`, accepting the
 same arguments as :py:meth:`pyvo.registry.search`.  This function simply
 returns the ADQL query that search would execute.  This is may be useful
 to construct custom RegTAP queries, which could then be executed on
@@ -130,7 +130,7 @@ you would say:
   ...                             registry.Freetext("supernova"))
 
 After that, ``resources`` is an instance of
-:py:class:`pyvo.registry.regtap.RegistryResults`, which you can iterate over.  In
+:py:class:`~pyvo.registry.regtap.RegistryResults`, which you can iterate over.  In
 interactive data discovery, however, it is usually preferable to use the
 ``to_table`` method for an overview of the resources available:
 
@@ -171,7 +171,7 @@ title, description, and perhaps the access mode (“interface”) offered.
 In the list of interfaces, you will sometimes spot an ``#aux`` after a
 standard id; this is a minor VO technicality that you can in practice
 ignore.  For instance, you can simply construct
-:py:class:`pyvo.dal.TAPService`-s from ``tap#aux`` interfaces.
+:py:class:`~pyvo.dal.TAPService`-s from ``tap#aux`` interfaces.
 
 Once you have found a resource you would like to query, you can pick it
 by index; however,
@@ -183,7 +183,7 @@ are not), but it is rather clunky, and in the real VO short name
 collisions should be very rare.
 
 Use the ``get_service`` method of
-:py:class:`pyvo.registry.regtap.RegistryResource` to obtain a DAL service
+:py:class:`~pyvo.registry.regtap.RegistryResource` to obtain a DAL service
 object for a particular sort of interface.
 To query the fourth match using simple cone search, you would
 thus say:
@@ -198,6 +198,7 @@ thus say:
   ------------ ------------ -------- ----- ... ---- ------------ ------------
   117.98645833  73.00961111 0.588592   986 ...  NED 07 51 56.750 +73 00 34.60
 
+
 To operate TAP services, you need to know what tables make up a
 resource; you could construct a TAP service and access its ``tables``
 attribute, but you can take a shortcut and call a RegistryResource's
@@ -382,7 +383,7 @@ similar to :ref:`pyvo-resultsets`; just remember that for interactive
 use there is the ``to_tables`` method discussed above.
 
 The individual items are instances of
-:py:class:`pyvo.registry.regtap.RegistryResource`, which expose many
+:py:class:`~pyvo.registry.regtap.RegistryResource`, which expose many
 pieces of metadata (e.g., title, description, creators, etc) in
 attributes named like their RegTAP counterparts (see the class
 documentation).  Some attributes deserve a second look.
@@ -569,29 +570,40 @@ should catch errors and, at least in interactive sessions, provide some
 way to interrupt overly long queries.  Here is an example for how to
 query all obscore services; remove the ``break`` at the end of the loop
 to actually do the global query (it's there so that you don't blindly
-run all-VO queries without reading at least this sentence)::
-
-    from astropy import table
-    from pyvo import registry
-
-    QUERY = "SELECT TOP 1 s_ra, s_dec from ivoa.obscore"
-
-    results = []
-    for svc_rec in registry.search(
-              datamodel="obscore", servicetype="tap"):
-          print("Querying {}".format(svc_rec.res_title))
-          try:
-              svc = svc_rec.get_service("tap")
-              results.append(
-                  svc.run_sync(QUERY).to_table())
-          except KeyboardInterrupt:
-              # someone lost their patience with a service.  Query next.
-              pass
-          except Exception as msg:
-              # some service is broken; you *should* complain, but
-              print("  Broken: {} ({}).  Complain to {}.\n".format(
-                  svc_rec.ivoid, msg, svc_rec.get_contact()))
-          break
-
-    total_result = table.vstack(results)
-    print(total_result)
+run all-VO queries without reading at least this sentence):
+
+.. doctest-remote-data::
+
+   >>> from astropy.table import vstack
+   >>> from pyvo import registry
+   >>>
+   >>> QUERY = "SELECT TOP 1 s_ra, s_dec from ivoa.obscore"
+   >>>
+   >>> results = []
+   >>> for i, svc_rec in enumerate(registry.search(datamodel="obscore", servicetype="tap")):
+   ...       # print("Querying {}".format(svc_rec.res_title))
+   ...       try:
+   ...           svc = svc_rec.get_service(service_type="tap", lax=True)
+   ...           results.append(
+   ...               svc.run_sync(QUERY).to_table())
+   ...       except KeyboardInterrupt:
+   ...           # someone lost their patience with a service.  Query next.
+   ...           pass
+   ...       except Exception as msg:
+   ...           # some service is broken; you *should* complain, but
+   ...           #print("  Broken: {} ({}).  Complain to {}.\n".format(
+   ...           pass #    svc_rec.ivoid, msg, svc_rec.get_contact()))
+   ...       if i == 5:
+   ...           break
+   >>> total_result = vstack(results)  # doctest: +IGNORE_WARNINGS
+   >>> total_result  # doctest: +IGNORE_OUTPUT
+   <Table length=5>
+          s_ra               s_dec
+          deg                 deg
+        float64             float64
+   ------------------ -------------------
+             350.4619            -9.76139
+     208.360833592735    52.3611106494996
+     148.204840298431    29.1690999975089
+           243.044008          -51.778222
+   321.63278049999997 -54.579285999999996

docs/utils/index.rst

@@ -0,0 +1,16 @@
+.. _pyvo-utils:
+
+***************************
+PyVO utils (``pyvo.utils``)
+***************************
+
+
+This module contains utilities and base classes intended for internal use
+within PyVO or other dependent libraries.
+
+
+Reference/API
+=============
+
+.. automodapi:: pyvo.utils.xml.elements
+    :no-inheritance-diagram:

docs/utils/prototypes.rst

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

pyvo/auth/authsession.py

@@ -53,7 +53,7 @@ def update_from_capabilities(self, capabilities):
         Parameters
         ----------
         capabilities : object
-            List of `~pyvo.io.vosi.voresource.Capabilities`
+            List of `~pyvo.io.vosi.voresource.Capability`
         """
         self._auth_urls.update_from_capabilities(capabilities)
 

pyvo/auth/authurls.py

@@ -25,7 +25,7 @@ def update_from_capabilities(self, capabilities):
         Parameters
         ----------
         capabilities : object
-            List of `~pyvo.io.vosi.voresource.Capabilities`
+            List of `~pyvo.io.vosi.voresource.Capability`
         """
         for c in capabilities:
             for i in c.interfaces:

pyvo/dal/__init__.py

@@ -9,7 +9,7 @@
 from .query import DALService, DALQuery, DALResults, Record
 
 from .sia import SIAService, SIAQuery, SIAResults, SIARecord
-from .sia2 import SIA2Service, SIA2Query, SIA2Results
+from .sia2 import SIA2Service, SIA2Query, SIA2Results, ObsCoreRecord
 from .ssa import SSAService, SSAQuery, SSAResults, SSARecord
 from .sla import SLAService, SLAQuery, SLAResults, SLARecord
 from .scs import SCSService, SCSQuery, SCSResults, SCSRecord
@@ -27,7 +27,7 @@
     "DALQuery", "SIAQuery", "SIA2Query", "SSAQuery", "SLAQuery", "SCSQuery", "TAPQuery",
     "DALResults",
     "SIAResults", "SIA2Results", "SSAResults", "SLAResults", "SCSResults", "TAPResults",
-    "Record",
+    "Record", "ObsCoreRecord",
     "SIARecord", "SSARecord", "SLARecord", "SCSRecord",
     "AsyncTAPJob",
     "DALAccessError", "DALProtocolError", "DALFormatError", "DALServiceError",