amwa-tv / is-template

Template repo for NMOS specifications

[Work In Progress] AMWA NMOS Template Specification

This repository holds the source for this Specification, part of the family of Networked Media Open Specifications from the Advanced Media Workflow Association

What does it do?

• It provides a template for AMWA NMOS Interface Specifcations.

Why does it matter?

• It helps ensure consistency between NMOS Specifications.
• It helps us test our continuous integration.

How does it work?

• It contains examples of documentation, APIs, schemas, and examples
• It provides a style guide and other advice for specification authors
  • This includes how to configure the repo for automatic linting and rendering to specs.amwa.tv
• Select AMWA-TV/is-template as the template when creating the new repo.

Getting started

There is more information about the NMOS Specifications and their GitHub repos at https://specs.amwa.tv/nmos.

is-template's Issues

Blank issue test

Test feature request, please ignore

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Test issue, please ignore

Testing slack notifications

A third test issue, please ignore

test, please ignore

nothing to see

Test issue one

Test issue, please ignore

NOthing to see here

One more test issue, please ignore

Sample Input

n/a

Test if this gets two labels

Item one

Issue created from test Kanban project

Rename "html-APIs" to "APIs"

We used “html-APIs” in the early days of NMOS in the example of using raml2html, and that got copied across to the gh-pages builds. But it’s a bit of anomaly now as we don't have html-docs or html-examples, so should be renamed to "APIs" for consistency across all repos (including the menus etc.)

Test issue created from slack app. Please ignore

As you haven't ignored it... this was created with

/github open amwa-tv/nmos-template custom.md

Try out the project issues beta before our access expires!

I think we have till March 31st, which is tomorrow!

Test bug report, please ignore

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

Make it easier to navigate from docs to API/schemas and follow $ref

Navigating from the docs part of an NMOS spec to the relevant API/schemas, and between $ref-ed schemas isn't easy for readers on amwa-tv.gtihub.io at the moment. The ghpages renderings of the docs are great, but the flat listing of the schemas directory and the simple rendering of each schema (even though they're pretty printed) makes them harder to user. The fact that the RAML rendering doesn't handle $ref, often makes that less useful as well.

If we could render schemas so the reader could follow $ref that would help quite a bit. Adding some cross links from the docs would help too.

I don't know if we could use the "description" properties from the schemas in some other ways as well - e.g. a property index?

[Bug]: test, please ignore

Sample Input

some text

Test feature request please ignore

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when...

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Header and menus not visible on rendered API pages

I think because these miss the full Jekyll processing they don't get the default layout that other pages do, but perhaps with some additional scripting this can be added?

Consider adding markdown linting

Recent great work to add JSON and RAML linting will make maintaining the quality of our specs easier. Linting of Markdown documentation would also help.

Looks like there are several tools out there already (choose your preference for CI, ruby, python, js) with common rule sets and the ability to extend with our own AMWA/NMOS specific rules.

For example, it's currently the case that IS-04, -05, -06, -07 all have slight inconsistencies between their docs/ filenames, initial headings in those files, and link text to that file from others. A few regex searches across these four repos finds a few cross-links mentioning section number, while mostly they don't; also a few different styles of numbering sub-sections within a Markdown file (unnumbered; numbered as 1, 2, 2.1, 3; numbered as N.1, N.2, N.2.1, N.3; with/without trailing dot).

(This may be a separate issue, but I also find it intermittently annoying that there's no easy way of reading to the next page of the documentation, or navigating to child/parent pages, in the NMOS repos or generated docs. E.g. consider what would be useful links from https://amwa-tv.github.io/nmos-discovery-registration/tags/v1.3/docs/2.0._APIs.html.)

Test Issue created with Custom issue template

Another issue

Make this a real template for creating new NMOS repos

At the moment nmos-template is mostly used for testing rendering, linting, CI, etc. Consider making it a template that can be used to create new repos. Possibly multiple templates (nmos-template-is, nmos-template-bcp...?) for different types of repo. Possibly include some history to help with merging changes later. Could also include instructions for setting up the CI.

Test issue: please ignore

This is for testing dashboard CI

Add a CONTRIBUTING.md

This should reference anything we need to about contribution agreements (for AMWA/non-AMWA members) and the defined practice used for repository branches from the wiki

Bare URLs in Markdown don't get made into links

E.g. in the IS-04 "Overview" source doc, http://jt-nm.org/ is rendered as a link.* That's nice.

But in the IS-04 "Overview" rendered doc, that text is not rendered as a link. That's a shame.

*This is a "GitHub Flavor" Markdown extension, I believe.

Another test issue, please ignore

Testing labels

Another test issue, please ignore

Nothing to see

A fourth test issue, please ignore

Ampersands render as '&' in some places

Event & Tally in description and title here: https://amwa-tv.github.io/nmos-event-tally/tags/v1.0.1/APIs/schemas/with-refs/source.html

Event & Tally in (the same file source) description and title here: https://amwa-tv.github.io/nmos-event-tally/tags/v1.0.1/APIs/EventsAPI.html#sources__sourceid__get

NB Pete has edited Gareth's URLs following renaming html-APIs -> APIs

Move common gh-pages code into separate repo(s)

Now we have seven IS's, there's a lot of copying required every time we change how gh-pages is built. This could be separated out.

Test custom issue, please ignore

JSON Formatter reorders properties

According to https://github.com/callumlocke/json-formatter/blob/master/README.md#why-are-object-keys-sometimes-in-the-wrong-order, this is a browser feature.

But I think it really would help readability of the JSON Schemas if the "title", "description" (and then probably "type") fields were displayed before the other JSON Schema keywords like "anyOf", etc. (On the other hand, "$schema" is just noise!)

Perhaps we could arrange that without resorting to a different JSON parsing technique to keep the as-written order or specifying the order of every last property out-of-band?

Similar issue with examples - which have also been authored with a property ordering to aid readability - but maintaining the as-written order is probably the only way to solve that.