xodio / xod-docs Goto Github PK

Rationale

XOD docs in this repository is a code that should be formatted properly. We have Prettier, but formatting with it is not enforced. We can’t actually make pretty-printing check a part of PR validation because it is too strict, thus it will confuse people who just want to fix a typo involving a slight paragraph reflow. Such PRs should not trigger a CI error.

So, a linter should be more relaxed than the prettier check. Here is a possible solution: https://github.com/markdownlint/markdownlint

Acceptance criteria

• I can yarn lint to check everything with the linter
• Max line length is set to 100
• All existing content is tweaked to pass the linter check
• After doing yarn prettier:all the yart lint produces no errors
• CircleCI is set up and invokes the linter on PRs

In the Fritzing diagram in 110-ldr the leg of the photosensor's voltage divider with the resistor is tied to the +5 volt rail. I think that should actually be tied to ground.

Reference

These topics are important to make new C++ nodes but are not covered anyhow:

• Reading XOD strings: iterating, dumping to a buffer
• Producing XOD strings: views, lifetime, double buffering
• Using custom type lists, implementing new view types

May reuse parts of the xodio/xod#1769 description

The only way to learn about in is through Medium announce of 0.25.0.

The Data Types Reference should describe the Errcode data type and list all its possible values.

The Shortcuts reference page always shows shortcuts for both Mac and PC producing clutter. A reader either uses a Mac or PC, let’s show only shortcuts relevant to him. A small embedded JS script can determine the reader’s OS and hide uninteresting shortcuts/items.

As mentioned in #63 (comment):

We have a few conventions that are scattered through the docs or even unwritten.
For example:

We have a few conventions that are scattered through the docs or even unwritten.
For example:

• any nodes that create a new type to work with hardware should be named as xxx-device
• node that initialises hardware module should be named init
• names of any nodes which do instructions "what to do" in imperative style must begin with a verb (init, read-byte, pair-tag, write-line, etc)
• nodes that "unfold" complex types into more primitive ones are named unpack-xxx
• example patches are named example-xxx
  (and probably a few others that I forgot to mention)

It will be cool to summarize these in a single guide article.

In the tutorial. The Diagram shows the button set to D0
In the Pictorial, the Button is wired to D13

This created confusion when I went to try the tutorial. What saved me is that it specifically states to set the port value of the button node. this created some confusion to set to 0 per picture or 13 per the wire diagram.

Currently, the shortcuts reference list items through plain HTML tables.

The items are a highly structured data that might be defined in a YAML file. This way is preferable because if we want to make a slight change in the HTML markup, we are in trouble: changes in every line of the table across all translations will be required.

To support translations the YAML source can have a separate description field for every language:

- shortcut:
    mac: ⌘ N
    pc: Ctrl+N
    action:
      EN: "New patch"
      DE: "Neu patch"
      RU: "Новый патч"

The https://xod.io/docs/reference/globals/ article is required by xodio/xod#1889

Let’s document all existing globals there.

In PR xodio/xod#1512 was added port literals for STM32, like "PA13", "PB8" and etc.
We have to update port literals in the docs.