Skip to content
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

Merged
merged 42 commits into from
Aug 5, 2020
Merged

S2025 - documentation only. #133

merged 42 commits into from
Aug 5, 2020

Conversation

SharonGoliath
Copy link
Collaborator

No description provided.

@coveralls
Copy link

coveralls commented Jul 22, 2020

Coverage Status

Coverage decreased (-0.05%) to 90.804% when pulling 5316414 on SharonGoliath:s2025 into 5e867ef on opencadc:master.

@SharonGoliath SharonGoliath requested a review from andamian August 4, 2020 23:09
doc/README.md Show resolved Hide resolved
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.
Copy link
Contributor

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?

Copy link
Collaborator Author

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:
Copy link
Contributor

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.

Copy link
Collaborator Author

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update to AS URL.

Copy link
Collaborator Author

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?

Copy link
Contributor

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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Broken link.

Copy link
Collaborator Author

@SharonGoliath SharonGoliath Aug 5, 2020

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

Copy link
Contributor

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.

Copy link
Collaborator Author

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?

Copy link
Contributor

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:

Copy link
Contributor

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.

Copy link
Collaborator Author

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Broken link

Copy link
Collaborator Author

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.


* 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/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What service?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added "Archive Metadata S"


python
> import caom2utils
> pydoc caom2utils.fits2caom2.ObsBlueprint
Copy link
Contributor

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.

Copy link
Collaborator Author

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.
Copy link
Contributor

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

Copy link
Contributor

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.

@andamian andamian merged commit 8886a86 into opencadc:master Aug 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants