nasa-ammos / aerie-docs Goto Github PK

Docs need to be made for creating/restoring a snapshot via the API

Currently we have two different 'parameters' docs on mission modeling:

• https://nasa-ammos.github.io/aerie-docs/mission-modeling/activity-types/parameters/
• https://nasa-ammos.github.io/aerie-docs/mission-modeling/parameters/

We should consolidate them.

Subtasks:

• Remove the API mutation for creating simulations
• Add an API mutation to update simulation bounds and simulation template bounds
• Add arguments and bounds to Query for Simulation Results
• Add a mutation to insert a simulation template
• Add querying for resources at a time

We need to document how to use incons for simulation runs. Basic idea is to:

• Create an incon file using this API
• Upload the incon file to the Aerie file store (via Gateway)
• Set the incon file in the simulation config
• Simulate

Docs Ticket for NASA-AMMOS/aerie#1418.

Add API Docs for the Mission Model showing how to query for Hasura Event logs.

Example query:

query {
  mission_model{
    id
    refresh_activity_type_logs { success }
    refresh_resource_type_logs { success }
    refresh_model_parameter_logs { success }
  }
}

I would like to add a bit of background theory to the documentation. The current overview (and everything else) is highly focused on the java implementation of Aerie. I would like to explain it from a system engineer's perspective: why we need a planner, the system problem it solves, and a little bit of a theoretical basis in control theory.

My suggestion is to add a section under Mission Modeling to explain basic theory, define terms, etc., to explain how to think about this before you jump into how to code it up.
We might also beef up the Concept of Operations to introduce and explain the planning context a bit more. Current documentation is from the POV of someone experienced in planning who understands the legacy problems Aerie is designed to fix. Probably better to just explain what it IS/DOES and why and maybe move the legacy stuff to a History section.

Coming at this from a system engineer's perspective, my goal is to make the docs explain Aerie to a system engineer user or stakeholder who wants to understand how/why they would use Aerie in a project context and not how to code it.
I'm willing to help update the docs to do this.

On docs page https://nasa-ammos.github.io/aerie-docs/overview/concept-of-operations/

Whereas, principles of and simulation are embarrassingly similar for activities and commands.

On the other end of the spectrum, a mission can choose to manually [create?] activity plans, basically not utilizing modeling, simulation or scheduling capabilities, while leveraging command expansion to automate sequence generation based on planning inputs.

Our docs have basic info on how to get started mission modeling. It would be nice to have a targeted tutorial on how to start building a mission model from scratch starting with our template model. Think the Svelte tutorial but for mission modeling!

API Playground docs need to be updated to reflect changes in NASA-AMMOS/aerie-gateway#50

Documentation ticket for: NASA-AMMOS/aerie#995

Docs are needed for:

• Adding a preset
• Assigning a preset to an activity

Time is an important concept in planning and scheduling, and it is also an important concept in discrete event simulation. Our documentation should have a page explaining how Aerie treats time, as well as show examples and recommendations for how to map a user's time scale(s) into Aerie time.

Checked for duplicates

Yes - I've already checked

Is this a regression?

No - This is a new bug

Version

1.11.09

Describe the bug

Installing aerie-docs dependencies as described in https://github.com/NASA-AMMOS/aerie-docs/blob/develop/CONTRIBUTING.md

When running nvm install, I get a number of vulnerabilities (initially 105)
_audited 1147 packages in 4.541s
200 packages are looking for funding
run npm fund for details
found 105 vulnerabilities (87 moderate, 18 high)
run npm audit fix to fix them, or npm audit for details

npm audit fix does not fix them. After updating multiple libraries, I get vulnerabilities down to 24
205 packages are looking for funding
run npm fund for details_

24 vulnerabilities (10 moderate, 14 high)

To address issues that do not require attention, run:
npm audit fix
Some issues need review, and may require choosing
a different dependency.
Run npm audit for details.

The output of npm audit fix is provided below:

Reproduction

No reproduction needed

Logs

_up to date, audited 1165 packages in 3s

202 packages are looking for funding
  run `npm fund` for details

# npm audit report

got  <11.8.5
Severity: moderate
Got allows a redirect to a UNIX socket - https://github.com/advisories/GHSA-pfrx-2q88-qq97
No fix available
node_modules/got
  package-json  <=6.5.0
  Depends on vulnerable versions of got
  node_modules/package-json
    latest-version  0.2.0 - 5.1.0
    Depends on vulnerable versions of package-json
    node_modules/latest-version
      update-notifier  0.2.0 - 5.1.0
      Depends on vulnerable versions of latest-version
      node_modules/update-notifier
        @docusaurus/core  <=2.4.1
        Depends on vulnerable versions of @docusaurus/mdx-loader
        Depends on vulnerable versions of update-notifier
        node_modules/@docusaurus/core
          @docusaurus/plugin-debug  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          node_modules/@docusaurus/plugin-debug
          @docusaurus/plugin-google-analytics  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          node_modules/@docusaurus/plugin-google-analytics
          @docusaurus/plugin-google-gtag  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          node_modules/@docusaurus/plugin-google-gtag
          @docusaurus/plugin-google-tag-manager  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          node_modules/@docusaurus/plugin-google-tag-manager
            @docusaurus/preset-classic  <=2.4.1
            Depends on vulnerable versions of @docusaurus/core
            Depends on vulnerable versions of @docusaurus/plugin-content-blog
            Depends on vulnerable versions of @docusaurus/plugin-content-docs
            Depends on vulnerable versions of @docusaurus/plugin-content-pages
            Depends on vulnerable versions of @docusaurus/plugin-debug
            Depends on vulnerable versions of @docusaurus/plugin-google-analytics
            Depends on vulnerable versions of @docusaurus/plugin-google-gtag
            Depends on vulnerable versions of @docusaurus/plugin-google-tag-manager
            Depends on vulnerable versions of @docusaurus/plugin-sitemap
            Depends on vulnerable versions of @docusaurus/theme-classic
            Depends on vulnerable versions of @docusaurus/theme-common
            Depends on vulnerable versions of @docusaurus/theme-search-algolia
            node_modules/@docusaurus/preset-classic
          @docusaurus/plugin-sitemap  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          node_modules/@docusaurus/plugin-sitemap
          @docusaurus/theme-mermaid  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          Depends on vulnerable versions of @docusaurus/theme-common
          node_modules/@docusaurus/theme-mermaid
          @docusaurus/theme-search-algolia  <=2.4.1
          Depends on vulnerable versions of @docusaurus/core
          Depends on vulnerable versions of @docusaurus/plugin-content-docs
          Depends on vulnerable versions of @docusaurus/theme-common
          node_modules/@docusaurus/theme-search-algolia

trim  <0.0.3
Severity: high
Regular Expression Denial of Service in trim - https://github.com/advisories/GHSA-w5p7-h5w8-2hfq
fix available via `npm audit fix`
node_modules/trim
  remark-parse  <=8.0.3
  Depends on vulnerable versions of trim
  node_modules/remark-parse
    @mdx-js/mdx  <=1.6.22
    Depends on vulnerable versions of remark-mdx
    Depends on vulnerable versions of remark-parse
    node_modules/@mdx-js/mdx
      @docusaurus/mdx-loader  <=2.4.1
      Depends on vulnerable versions of @mdx-js/mdx
      node_modules/@docusaurus/mdx-loader
        @docusaurus/plugin-content-blog  <=2.4.1
        Depends on vulnerable versions of @docusaurus/core
        Depends on vulnerable versions of @docusaurus/mdx-loader
        node_modules/@docusaurus/plugin-content-blog
        @docusaurus/plugin-content-docs  <=2.4.1
        Depends on vulnerable versions of @docusaurus/core
        Depends on vulnerable versions of @docusaurus/mdx-loader
        node_modules/@docusaurus/plugin-content-docs
        @docusaurus/plugin-content-pages  <=2.4.1
        Depends on vulnerable versions of @docusaurus/core
        Depends on vulnerable versions of @docusaurus/mdx-loader
        node_modules/@docusaurus/plugin-content-pages
        @docusaurus/theme-classic  <=2.4.1
        Depends on vulnerable versions of @docusaurus/core
        Depends on vulnerable versions of @docusaurus/mdx-loader
        Depends on vulnerable versions of @docusaurus/plugin-content-blog
        Depends on vulnerable versions of @docusaurus/plugin-content-docs
        Depends on vulnerable versions of @docusaurus/plugin-content-pages
        Depends on vulnerable versions of @docusaurus/theme-common
        node_modules/@docusaurus/theme-classic
        @docusaurus/theme-common  <=2.4.1
        Depends on vulnerable versions of @docusaurus/mdx-loader
        Depends on vulnerable versions of @docusaurus/plugin-content-blog
        Depends on vulnerable versions of @docusaurus/plugin-content-docs
        Depends on vulnerable versions of @docusaurus/plugin-content-pages
        node_modules/@docusaurus/theme-common
    remark-mdx  <=1.6.22
    Depends on vulnerable versions of remark-parse
    node_modules/remark-mdx

23 vulnerabilities (9 moderate, 14 high)

To address issues that do not require attention, run:
  npm audit fix

Some issues need review, and may require choosing_

System Info

Reference machine: Ubuntu 22 amd64 running as guest with VMWARE Workshtation 17 for Windows 10

Severity

Moderate

Including documentation illustrating how to model a unitary goal, i.e. a goal that results in the instantiation of a single activity at a specific time instant or time window

We currently only have API docs for both of these topics.

The resources and models document is out of date. It needs to be updated with concrete examples of the different resources and how to add them to a model.

There are two new arguments in aerie-db-migration, env-path, and network-location as of #845.

The current documentation for the controllable parameter feature gives multiple examples that show a parameter with int type. In fact, Aerie will raise an error for int types and the only correct parameter type is protocol.Duration.

@Parameter public long durationInSeconds;

Internal ticket: https://jira.jpl.nasa.gov/browse/AERIEQS-334

This is a very useful capability that saves users time. We should document it, and include it in any tutorial #48 we make.

Should explain how to use MerlinExtension with JUnit, with examples.

Add documentation for @unit parsing. This will include how to parse units from @params, @registeredStates, and @computedAttributes.

This should include how to author custom sequences using the UI. These docs should be in the sequencing section.

• Include basic usage on the timeline editor with either screenshots or videos.
  • Add timeline row, and layers
• Make sure to note activity layer drawing height, overdrawing conditions

Try just time boxing this to an hour (2 max), we only need some initial docs and can add more tickets later to flesh them out

Create user-facing docs on how to create/modify/delete anchors via the UI and API

Similar to #48, we should have a tutorial for authoring basic scheduling goals. The current documentation does explain the expressions available and has some examples, but has a lot of detail upfront, which can feel a bit overwhelming.

Add docs for how to add/customize roles. Go over the function/action permissions using the keys from here. Mention that the UI assumes that all roles that are allowed to update/insert into a table can update/insert into the same set of columns.

I finally got to reading the Mission Modeling PDF (from https://github.com/NASA-AMMOS/aerie-docs/actions/runs/7716737111) and noticed that several of the file examples are missing. When I look at the online documentation, it looks like they are broken there too:
https://nasa-ammos.github.io/aerie-docs/mission-modeling/introduction/

The software design document (SDD) is needed as part of our formal release documentation. It is useful because it communicates many of our design decisions in Aerie.

• Migrate current SDD to Aerie public documentation website
• Complete the rest of the SDD

There are several sample API queries and mutations that we used to have included in our docs. This ticket is to expand our new API docs with these missing queries, updated to match the current doc style/naming conventions/API spec.

The Simulation Configuration API docs need to be updated to remove mentions of the Simulation Configuration Template specifying simulation bounds. Additionally, the mention that the bounds must be specified first should be removed.

Document the modifications done in the eDSL that allow to model flexible intervals with relative start/end timepoints wrt other activities. These modification enables the representation of allen relations between two activities in a coexistence goal

Checked for duplicates

Yes -- New feature, new files.

Alternatives considered

Yes - This is a Lab-approved and suggested addition to all NASA-AMMOS repositories.

Related problems

Many repos don't provide comprehensive documentation and/or are missing key areas of standardized documentation focus. This feature adds standardized documentation per Lab-approved standards.

Describe the feature request

A number of template and documentation files are being added to the repository in support of the SLIM project. These files are suggested by MGSS and will serve to promote cohesion between NASA-AMMOS products. The files provided are tailored to the current repository with minimal integration assistance and upkeep requested of the CogE and/or developers.

See commit history in the slim_infusion branch for added files.

As of the Versioning Constraints PR, the API docs for constraints will need to be updated.