diff --git a/content/en/_index.md b/content/en/_index.md index db7ebff..d68140f 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -19,7 +19,7 @@ Polaris provides a web UI for both submitting and managing astronomical observin multiple telescopes. -In addition it provides components that enable the export of proposals and to allow their manipulation off-line +In addition, it provides components that enable the export of proposals and to allow their manipulation off-line {{% /blocks/lead %}} diff --git a/content/en/docs/Getting started/Creating Proposals/_index.md b/content/en/docs/Getting started/Creating Proposals/_index.md new file mode 100644 index 0000000..f061af8 --- /dev/null +++ b/content/en/docs/Getting started/Creating Proposals/_index.md @@ -0,0 +1,62 @@ +--- +title: Creating Proposals +date: 2023-11-01 +description: > + _Quick start guide to creating a new **Proposal** using Polaris_ +categories: [Examples] +tags: [test, sample, docs] +--- + +###### First, Login + +If you haven't registered with and logged-in to Polaris please do so [now](tbc). + +## Click the **Create a new proposal** button + +polaris landing page, highlighting the create a new proposal button +
+
+ +This will bring up the new **Proposal** details form. + +## Fill in the proposal details form and click **Create** + +create proposal details +
+
+ +The basic details of an **Observing Proposal** are the title, a brief summary, and the **Kind** of your proposal +either _STANDARD_, _SURVEY_, or _T.O.O._ (target-of-opportunity). These attributes can be changed after you create +the proposal. + +## The Proposal Overview + +Now that you have a created a new proposal you can see its **Overview** by clicking the dropdown +menu for the relevant proposal in the navigation pane on the left, and clicking on the _Overview_ +tab. + +the proposal overview +
+
+ +In the screenshot example we have given our proposal the title _An awesome proposal title_, filled +in the summary with a very brief summary (literally), and assigned it a **Kind** of _STANDARD_. Notice +that, as the creator of the new proposal, you will have been automatically assigned the **PI**, or +Principal Investigator, role for the proposal (in the example we used for the screenshots, the +username is also _PI_; nobody said we had to be inventive). + +## Next Steps: adding Targets and Technical Goals + +If you now try to go to the _Observations_ tab you will be presented with the following page: + +trying to add observation before adding targets and technical goals +
+
+ +In the Polaris app you must first add at least one observational **Target** and at least one **Technical +Goal** before you can generate an **Observation** for your proposal. Notice that the yellow text in the +screenshot is a link to take you to the corresponding page in the App. + +For the next steps in this guide, please follow either the **Adding Targets** link or the **Adding Technical Goals** +link, the order here does not matter. The **Building Observations** page assumes you have added at least one target +and at least one technical goal to your proposal. diff --git a/content/en/docs/Getting started/Creating Proposals/adding-targets.md b/content/en/docs/Getting started/Creating Proposals/adding-targets.md new file mode 100644 index 0000000..79cff7f --- /dev/null +++ b/content/en/docs/Getting started/Creating Proposals/adding-targets.md @@ -0,0 +1,58 @@ +--- +title: Adding Targets +date: 2024-03-04 +description: > + _Guide to adding observational **Targets** to your proposal_ +categories: [Examples] +tags: [test, sample, docs] +--- + +# Add a Target + +A fresh proposal will have no **Targets** added, and you will be presented with the following page: + +add a target +
+
+ +To add a **Target** click the _Add +_ button, which will bring up the _New Target_ form. + +new target form +
+
+ +In the screenshot you will see we have added the [Aladin Lite Sky Atlas](https://aladin.cds.unistra.fr/), +and we have found the _Crab Nebula_ using the **Lookup** function. This fills in the corresponding +positional and coordinate system data for the named target, and displays the target in the Sky Atlas. +Notice that the backend uses [Simbad](https://simbad.cds.unistra.fr/simbad/) to search for the named target, such that the name must +exist in their databases to be successful; an appropriate error notification is displayed if the +named target cannot be found. + +You may also simply click anywhere on the Sky Atlas and the corresponding positional details will be +updated in the RA and DEC fields (notice that these are currently displayed as degrees only, we have +development plans to add _HH:MM:SS_ format and to allow you to select between the units with which you +are most comfortable). + +You can also manually fill in the fields, the Sky Atlas will automatically change the view to those +coordinates. Notice that in this alpha version of Polaris, you can have any coordinate system you like, +so long as it's _J2000_. + +You may also change the name of the target after you have looked it up and before you save it as a +**Target**. To save, click the _Save_ button. This will return you to the _Targets_ tab of your proposal +now displaying the **Target** you just saved, and any other targets you may have added. + +list of targets +
+
+ +Please notice that the _Reference System_ should read _ICRS_ but due to some bug that has yet to be +squished it reads _unknown_; did I mention this was the alpha version? + +You may _Delete_ this target if you so wish, just remember that you need at least one target in order +to build an **Observation** for your proposal. + +# Next Step + +If you haven't already added a **Technical Goal** then please follow the guide [here](../adding-technical-goals). +If you have now added at least one **Target** and one **Technical Goal** to your proposal then please +follow the link to [**Building Observations**](../build-observation). \ No newline at end of file diff --git a/content/en/docs/Getting started/Creating Proposals/adding-technical-goals.md b/content/en/docs/Getting started/Creating Proposals/adding-technical-goals.md new file mode 100644 index 0000000..6ac0aab --- /dev/null +++ b/content/en/docs/Getting started/Creating Proposals/adding-technical-goals.md @@ -0,0 +1,46 @@ +--- +title: Adding Technical Goals +date: 2024-03-04 +description: > + _Guide to adding **Technical Goals** to your proposal_ +categories: [Examples] +tags: [test, sample, docs] +--- + +# Add a Technical Goal + +A fresh proposal will have no **Technical Goals** and you will be presented with the following page: + +no technical goals summary page +
+
+ +To add a **Technical Goal** click the _Add +_ button, which will bring up the _New Technical Goal_ form. + +new technical goals form +
+
+ +In the screenshot you can see we have filled out the _Performance Parameters_ with some values and their +corresponding units; the values in the screenshot are contrived for this guide. The units are selected via a +drop-down menu. These values are what you would like the observation to achieve, and are not necessarily strict +requirements. Further explanation of each field can be found [here](???) (to-do). The _Performance Parameters_ +are the minimum amount of information required to _Save_ (screenshot reads _Submit_ because alpha version) a +**Technical Goal**. For now, we ignore the _Spectral Window_ aspect of a **Technical Goal**, to be revisited later. + +After clicking _Save_ you will be brought back to the technical goals summary page, which should now display your +newly added **Technical Goal**. + +technical goals summary page +
+
+ +Unlike **Targets**, you can also _Edit_ and _Copy_ **Technical Goals** as well as _Delete_ them. This allows you +to change the attributes of an existing **Technical Goal**, or quickly add other **Technical Goals** that may have +similar _Performance Parameters_ and/or _Spectral Windows_ without having to re-input all the data. + +# Next Step + +If you haven't already added a **Target** then please follow the guide [here](../adding-targets). +If you have now added at least one **Target** and one **Technical Goal** to your proposal then please follow the +link to [**Building Observations**](../build-observation). \ No newline at end of file diff --git a/content/en/docs/Getting started/Creating Proposals/build-observation.md b/content/en/docs/Getting started/Creating Proposals/build-observation.md new file mode 100644 index 0000000..1b7272c --- /dev/null +++ b/content/en/docs/Getting started/Creating Proposals/build-observation.md @@ -0,0 +1,69 @@ +--- +title: Building Observations +date: 2024-03-04 +description: > + _Guide to building an **Observation** for your proposal_ +categories: [Examples] +tags: [test, sample, docs] +--- + +# Build an Observation + +After adding at least one **Target** and at least one **Technical Goal** you will see the following summary page +for **Observations**, which will be empty. + +empty Observations summary page +
+
+ +To build an **Observation** click the _Add +_ button, which will bring up the new observation form. + +new Observation form +
+
+ +In this screenshot we have already selected our **Target**, the "crab", and our **Technical Goal**, and have +selected the _Observation Type_ as _Calibration_ and the _Calibration intended use_ as _Pointing_. Notice that +the _Observation Type_ is a choice between _Target_ and _Calibration_, and if you select _Target_ there is no +"intended use" field; the **Target** is the intention of the **Observation**. For a _Calibration_ **Observation** +there are several "intended use" options to pick from; see the [documentation](???) (to-do) for details. + +Selecting the **Target**, **Technical Goal**, and _Observation Type_ is the minimum amount of information to _Save_ +an **Observation** to the database. However, for the **Proposal** to pass the server side validation before +submission, all **Observations** in the **Proposal** must have at least one **Timing Window**. + +A **Timing Window** is a timing constraint on the **Observation**, and consists of _start_ and _end_ times that +can be specified up to the minutes unit, an _avoid_ toggle switch that changes the meaning of the window, to be +explained presently, and an optional note to provide additional information if required. Typically, a +**Timing Window** will specify the range of times when the **Observation** should be performed i.e., the _avoid_ +toggle is unset. However, with the _avoid_ toggle set the window then specifies the range of times when the +**Observation** should **_not_** be performed. + +You can add as many **Timing Windows** to an **Observation** as required by your needs. Please note that the +_start_ time must be at an earlier time than the _end_ time, but that different **Timing Windows** may overlap. +In this case, it is recommended to write optional notes to provide context for anyone reviewing your proposal. +Notice that we assume all times are entered as UTC. + +With all that information entered, click _Save_ to save the **Observation** to your **Proposal**. This will +bring you back to the _Observations_ summary page, that will now contain your newly built **Observation**. + +Observations summary page +
+
+ +As with **Technical Goals** you may _Edit_ and _Copy_ **Observations** to avoid having to repeat data entry for +**Observations** that have similar attributes. For example, using the same **Target** but for different types, +_Target_ or _Calibration_, of **Observation** with perhaps the same **Technical Goal** and/or timing constraints. + +With an **Observation** now built both the **Target** and the **Technical Goal** to which is refers have their +_Delete_ button disabled. This prevents you from deleting either of these things while they are actively pointed +to by an **Observation**. In order to re-enable the _Delete_ button on **Targets** and **Technical Goals** you +must first delete all **Observations** that refer to them. + +In this alpha version of Polaris, once you have an **Observation** with at least one **Timing Window** in your +**Proposal** it will pass server side validation checks, and you may submit it for review. In subsequent versions, +you will also have to provide both **Scientific** and **Technical Justifications** to pass validation checks, and +it is likely more things will be added to the validation check in the future. + +To see how to submit your proposal for review please follow the guide at +[**Submitting Proposals**](../../submitting-proposals) \ No newline at end of file diff --git a/content/en/docs/Getting started/Submitting Proposals/_index.md b/content/en/docs/Getting started/Submitting Proposals/_index.md new file mode 100644 index 0000000..8f91652 --- /dev/null +++ b/content/en/docs/Getting started/Submitting Proposals/_index.md @@ -0,0 +1,47 @@ +--- +title: Submitting Proposals +date: 2024-03-04 +description: > + _Guide to submitting your **Proposal**_ +categories: [Examples] +tags: [test, sample, docs] +--- + +{{% pageinfo %}} +Please be aware that the submission functionality of Polaris is under active development such that this page +may very well be out-of-date. Please bear with us while we get around to updating this page. + +Last updated **2024-03-06** Polaris _alpha_ version. +{{% /pageinfo %}} + + +# Submit your Proposal + +Once you are happy with the details of your **Proposal**, and it has passed the server side validation checks +you may submit it for review. + +proposal submission ready +
+
+ +You will have to select the **Proposal Cycle** from the drop-down menu to which you wish to submit your **Proposal**. +Once selected the page will display the submission deadline for that cycle. + +Server side validation checks currently include: + +* the **Proposal** _Title_, _Summary_, and _Kind_ attributes are set (the App prevents you from leaving any of these blank) +* at least one **Observation** added with at least one **Timing Window** + * which requires at least one **Target** and at least one **Technical Goal** + +As we develop the server side validation checks this list will grow. For example, we'd expect that a **Proposal** +must have a **Scientific Justification** and a **Technical Justification** to be valid for review. Indeed, we +expect this list to expand significantly as we put Polaris in to beta-testing. + +If a **Proposal** doesn't pass the validation checks then you will be presented with the following page for the +_Submit_ tab of your proposal, which lists the problems. + +proposal submission not ready +
+
+ +Here we have created another proposal but haven't added any **Targets**, **Technical Goals**, or **Observations**. \ No newline at end of file diff --git a/content/en/docs/Getting started/_index.md b/content/en/docs/Getting started/_index.md index 85cec9e..2cbd3ac 100644 --- a/content/en/docs/Getting started/_index.md +++ b/content/en/docs/Getting started/_index.md @@ -1,35 +1,37 @@ --- title: Getting Started -description: What does your user need to know to try your project? +description: Prerequisites, Installation, and Core Setup categories: [Examples, Placeholders] tags: [test, docs] weight: 2 --- -{{% pageinfo %}} -This is a placeholder page that shows you how to use this template site. -{{% /pageinfo %}} +## Prerequisites -Information in this section helps your user try your project themselves. +**To be confirmed** -* What do your users need to do to start using your project? This could include downloading/installation instructions, including any prerequisites or system requirements. +## Installation +### For users +[Front end GUI](https://github.com/orppst/pst-gui) -* Introductory “Hello World” example, if appropriate. More complex tutorials should live in the Tutorials section. +[Front end CLI](https://github.com/orppst/pst-cli-app) - under development -Consider using the headings below for your getting started page. You can delete any that are not applicable to your project. +### For Developers +[Overarching project](https://github.com/orppst) -## Prerequisites +[Back end API](https://github.com/orppst/pst-api-service) -Are there any system requirements for using your project? What languages are supported (if any)? Do users need to already have any software or tools installed? +## Setup -## Installation +Go to the application URI (TBC) and register as a new user. +Then login with your new credentials where you will be asked to provide your organisation details by either selecting +from a list of existing institutions or supplying information about your organisation if not present in the list. -Where can your user find your project code? How can they install it (binaries, installable package, build from source)? Are there multiple options/versions they can install and how should they choose the right one for them? +## Get started -## Setup +Start by going to the **Creating Proposals** page. -Is there any initial setup users need to do after installation to try your project? +_Please note that the screenshots in this guide were taken using an alpha version of Polaris so may contain +some stylistic and naming differences to the version you are using._ -## Try it out! -Can your users test their installation, for example by running a command or deploying a Hello World example? diff --git a/content/en/docs/Getting started/creating-proposal.md b/content/en/docs/Getting started/creating-proposal.md deleted file mode 100644 index 92ff12e..0000000 --- a/content/en/docs/Getting started/creating-proposal.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Creating a Proposal -date: 2023-11-01 -description: > - A short lead description about this content page. It can be **bold** or _italic_ and can be split over multiple paragraphs. -categories: [Examples] -tags: [test, sample, docs] ---- - -{{% pageinfo %}} -This is a placeholder page. Replace it with your own content. -{{% /pageinfo %}} - - diff --git a/static/images/getting-started/observations_missing_target_goal.png b/static/images/getting-started/observations_missing_target_goal.png new file mode 100644 index 0000000..ca4d22a Binary files /dev/null and b/static/images/getting-started/observations_missing_target_goal.png differ diff --git a/static/images/getting-started/observations_new.png b/static/images/getting-started/observations_new.png new file mode 100644 index 0000000..765fb96 Binary files /dev/null and b/static/images/getting-started/observations_new.png differ diff --git a/static/images/getting-started/observations_none.png b/static/images/getting-started/observations_none.png new file mode 100644 index 0000000..c5d36db Binary files /dev/null and b/static/images/getting-started/observations_none.png differ diff --git a/static/images/getting-started/observations_some.png b/static/images/getting-started/observations_some.png new file mode 100644 index 0000000..590868c Binary files /dev/null and b/static/images/getting-started/observations_some.png differ diff --git a/static/images/getting-started/proposal_create.png b/static/images/getting-started/proposal_create.png new file mode 100644 index 0000000..4f3ebc4 Binary files /dev/null and b/static/images/getting-started/proposal_create.png differ diff --git a/static/images/getting-started/proposal_create_details.png b/static/images/getting-started/proposal_create_details.png new file mode 100644 index 0000000..d26df21 Binary files /dev/null and b/static/images/getting-started/proposal_create_details.png differ diff --git a/static/images/getting-started/proposal_overview.png b/static/images/getting-started/proposal_overview.png new file mode 100644 index 0000000..e174b30 Binary files /dev/null and b/static/images/getting-started/proposal_overview.png differ diff --git a/static/images/getting-started/proposal_overview_observation.png b/static/images/getting-started/proposal_overview_observation.png new file mode 100644 index 0000000..5945f7d Binary files /dev/null and b/static/images/getting-started/proposal_overview_observation.png differ diff --git a/static/images/getting-started/proposal_submission_not_ready.png b/static/images/getting-started/proposal_submission_not_ready.png new file mode 100644 index 0000000..a85c380 Binary files /dev/null and b/static/images/getting-started/proposal_submission_not_ready.png differ diff --git a/static/images/getting-started/proposal_submission_ready.png b/static/images/getting-started/proposal_submission_ready.png new file mode 100644 index 0000000..396a2c8 Binary files /dev/null and b/static/images/getting-started/proposal_submission_ready.png differ diff --git a/static/images/getting-started/targets_new.png b/static/images/getting-started/targets_new.png new file mode 100644 index 0000000..514db64 Binary files /dev/null and b/static/images/getting-started/targets_new.png differ diff --git a/static/images/getting-started/targets_none.png b/static/images/getting-started/targets_none.png new file mode 100644 index 0000000..4558403 Binary files /dev/null and b/static/images/getting-started/targets_none.png differ diff --git a/static/images/getting-started/targets_some.png b/static/images/getting-started/targets_some.png new file mode 100644 index 0000000..9c98e47 Binary files /dev/null and b/static/images/getting-started/targets_some.png differ diff --git a/static/images/getting-started/technical_goals_new.png b/static/images/getting-started/technical_goals_new.png new file mode 100644 index 0000000..1929a2c Binary files /dev/null and b/static/images/getting-started/technical_goals_new.png differ diff --git a/static/images/getting-started/technical_goals_none.png b/static/images/getting-started/technical_goals_none.png new file mode 100644 index 0000000..a4f631c Binary files /dev/null and b/static/images/getting-started/technical_goals_none.png differ diff --git a/static/images/getting-started/technical_goals_some.png b/static/images/getting-started/technical_goals_some.png new file mode 100644 index 0000000..6d0e23d Binary files /dev/null and b/static/images/getting-started/technical_goals_some.png differ