DOC: Change link targets at the protocol overview into pyVO docs; add brief intro for each service protocol #372
Conversation
There was a problem hiding this comment.
I leave the review of the actual text to others, but overall very much like the logic of the changes of keeping the docs self-contained and linking out to the difficult-to-read standard documents only as an external reference.
The minor change that I would like to see is to add internal sphinx references rather than use HTML anchors, I'm happy to help to figure those out.
Codecov Report
@@ Coverage Diff @@
## main #372 +/- ##
=======================================
Coverage 78.55% 78.55%
=======================================
Files 47 47
Lines 5564 5564
=======================================
Hits 4371 4371
Misses 1193 1193 📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
docs/dal/index.rst
Outdated
| database tables. Access is provided for both database and table metadata | ||
| as well as for actual table data. This version of the protocol includes | ||
| support for multiple query languages, including queries specified using | ||
| the Astronomical Data Query Language within an integrated interface. |
There was a problem hiding this comment.
Please introduce the ADQL acronym here by adding (ADQL). A link to the IVOA would also be nice.
docs/dal/index.rst
Outdated
| queries against an arbitrarily large list of astronomical targets, | ||
| providing a simple spatial cross-matching capability. | ||
| More sophisticated distributed cross-matching capabilities are possible by | ||
| orchestrating a distributed query across multiple TAP services. | ||
|
|
||
| Unlike the other services, this one works with tables queryable by an sql-ish | ||
| language called *ADQL* instead of predefined search constraints. |
There was a problem hiding this comment.
I would remove this paragraph since it's just duplicating the info now.
docs/dal/index.rst
Outdated
| The `Simple Image Access (SIA) <https://www.ivoa.net/documents/SIA/>`_ protocol | ||
| provides capabilities for the discovery, description, access, and retrieval | ||
| of multi-dimensional image datasets, including 2-D images as well as datacubes | ||
| of three or more dimensions. SIA data discovery is based on the ObsCore Data Model, |
docs/dal/index.rst
Outdated
| which primarily describes data products by the physical axes (spatial, spectral, | ||
| time, and polarization). Image datasets with dimension greater than 2 are often | ||
| referred to as datacubes, cube or image cube datasets and may be considered examples | ||
| of hypercube or n-cube data. In this document the term "image" refers to general |
There was a problem hiding this comment.
From "In this document ..." onwards, the info is not relevant to this documentation
| SSA-defined data model at access time by the service, so that client analysis | ||
| programs do not have to be familiar with the idiosyncratic details of | ||
| each data collection to be accessed. | ||
|
|
There was a problem hiding this comment.
This might be a bit too long and detailed as compared with the other ones.
There was a problem hiding this comment.
Thank you very much for your review, I made a couple of changes to the texts according to your suggestions. Please have a look if they are appropriate now.
chmmao
force-pushed
the
fix-protocol-links
branch
from
d8211f1
to
3199469
Compare
|
Anyone else wants to comment? |
|
On Tue, Nov 01, 2022 at 04:46:19PM -0700, Adrian wrote:
Anyone else wants to comment?
I like it, too.
|
|
Merged. @ChuanmingMao - thank you for your contribution! |
Background:
When I clicked on "TAP", for instance, on the opening page of the pyVO docs, I ended up at the IVOA documentation rather than the pyVO docs on how to use TAP, which is in my opinion not so convenient and straightforward.
Suggestion:
This PR attempts to improve the user experience(for a newcomer like me) by changing the link target of each service protocol to the position in pyVO docs on how to use them; it also adds brief introductions as to what the protocols are, and that's also where the former links into the IVOA doc repo now reside.