-
Notifications
You must be signed in to change notification settings - Fork 13
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
S2025 - documentation only. #133
Conversation
Address feedback from @dbohlender.
Address feedback from @dbohlender.
Address feedback from @dbohlender.
Incorporate feedback from @dbohlender.
Additional feedback from @dbohlender.
Additional feedback from @dbohlender.
Add an example of using a function to set a CAOM2 attribute, as per @dbohlender.
Remove references to development repository.
Remove reference to individual repository.
doc/README.md
Outdated
|
||
1. Copy the file `TEST_FILE.FITS` in the working directory. The metadata in this file will be described in the CAOM Observation created during this example. | ||
|
||
1. The example will cause an instance to be created in the [CAOM2 sandbox](http://sc2.canfar.net/search/). If you visit prior to the creation of the first CAOM instance for a `COLLECTION`, that `COLLECTION` will not show in the `Additional Constraints -> Collection` . Even after successful creation of a CAOM instance, it can take up to one day for the `COLLECTION` to be selectable from the UI. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel like this could be a bit clearer. The verb visit
confuses me a bit.
Also, maybe a short description of CAOM2 sandbox might be appropriate. Is the sandbox open for everyone to add records or prior A&A is required?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changed 'visit' to 'click the CAOM2 sandbox URL'.
Added three sentence description of sandbox.
Prior A&A is required, but that's already mentioned as item (iv), in Precondition 1.
AttributeError: module ‘enum’ has no attribute ‘IntFlag’ | ||
``` | ||
|
||
Ensure the version of vos is >= 3.1.1: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please update the vos
dependency in setup.cfg
file to be 3.1.1. so that troubleshooting would simply ask the user to make sure they are running the latest version of caom2utils
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did update the setup.cfg file for caom2utils, but I'll leave the trouble-shooting in the docs, because of the pip uninstall that's required, and not necessarily obvious.
@@ -0,0 +1,95 @@ | |||
# Working With CAOM2 | |||
|
|||
For observations to appear in [CADC search services](http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/), an observation must first be described by a CAOM record. That description will then need to be loaded into the CADC CAOM repository, using a CADC web service. This web service will create a corresponding database record. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Update to AS URL.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand this comment.
It's not to /en/search or to /fr/recherche because of the bi-lingualism. Is that what you're referring to?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. This documentation is in English so /en/search
would be justified.
@@ -0,0 +1,46 @@ | |||
# How to describe and load a CAOM2 Observation using the Command Line | |||
|
|||
1. Ensure the pre-conditions as described [here](https://github.com/opencadc/caom2tools/blob/master/doc#preconditions) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Broken link.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The link will work after the pull request has been accepted and merged.
@@ -0,0 +1,46 @@ | |||
# How to describe and load a CAOM2 Observation using the Command Line | |||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know who the audience is for this doc but I would add a bit more context. A short intro paragraph stating the purpose of the exercise and the required steps that are further detailed below. What the 2 tools (caom2gen
and caom2repo
) are designed to accomplish. etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't that context provided here: http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/en/doc/caom/?
These docs are not meant to stand alone. Should they be?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's no mentioning of these tools in that document. This document is "closer" to the tools so I would add it here.
``` | ||
|
||
1. Everything after this is making refinements to the mapping between file content and CAOM2 instance members. This means issuing `caom2-repo update` commands, instead of `caom2-repo create` commands, to make changes on the server. However, caom2-repo is particular about its ids, so after the first successful execution of caom2-repo create, do this: | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I realize that from a usability point of view this is a bit crazy to require users to download the observation with the DB keys and use those for updates. I'm thinking we should add a flag to create
to override existing observations if they exist.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See #134
* what information to obtain from the FITS header, | ||
* defaults in case the FITS header is incomplete, | ||
* hard-coded value when the FITS header should be ignored, or doesn't have information, and | ||
* python functions which will be loaded and executed at run-time to augment FITS keyword values. See [this section](https://github.com/opencadc/caom2tools/blob/master/doc/user/script_description.md#putting-it-all-together) for an example. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Broken link
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It will work after the pull request is accepted and merged.
doc/user/script_description.md
Outdated
|
||
* a description of the latest version of the CAOM2 model, see [here](http://www.opencadc.org/caom2/). | ||
|
||
* a description of the operational version of the CADC service, see [here](http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/ams/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What service?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added "Archive Metadata S"
doc/user/script_description.md
Outdated
|
||
python | ||
> import caom2utils | ||
> pydoc caom2utils.fits2caom2.ObsBlueprint |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I suspect you can simply run pydoc caom2utils.fits2caom2.ObsBlueprint
command to achieve the same thing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It says what you said.
@@ -0,0 +1,95 @@ | |||
# Working With CAOM2 | |||
|
|||
For observations to appear in [CADC search services](http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/), an observation must first be described by a CAOM record. That description will then need to be loaded into the CADC CAOM repository, using a CADC web service. This web service will create a corresponding database record. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. This documentation is in English so /en/search
would be justified.
@@ -0,0 +1,46 @@ | |||
# How to describe and load a CAOM2 Observation using the Command Line | |||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's no mentioning of these tools in that document. This document is "closer" to the tools so I would add it here.
No description provided.