Provide .nengobones.yml reference documentation

[jgosmann]

While there is some documentation on the .nengobones.yml file, I do not find it that helpful to get started. When working from an example file (e.g. the provided .nengobones.yml), I have trouble finding the keywords I want to look up. I'm not even sure if pkg_name and repo_name are properly documented.

Also I'm missing a quick overview of the hierarchical structure in that file.

[jgosmann]

Also what templates for ci_scripts are there and what do they do?

[jgosmann]

Specific questions:

• What does bones_install do?
• What exactly does it mean to divide jobs into stages?
• In the .nengobones.yml of Nengo, how do the script and env entries on the same indentation level interact?

[drasmuss]

Nengo Bones is still under active development, so the documentation is a work in progress. Our apologies that you do not find the current documentation that helpful.

To answer your specific questions:

I'm not even sure if pkg_name and repo_name are properly documented.

These are documented in #17, which will be merged soon.

Also I'm missing a quick overview of the hierarchical structure in that file.

Each templated file has its own section, with name matching the filename (e.g. .travis.yml has a travis_yml section, .codecov.yml has the codecov_yml section, etc.). Is that what you mean about the hierarchical structure?

What does bones_install do?

This controls which version of nengo-bones is used in TravisCI. It's basically only used for testing purposes (e.g. if you want to check some downstream repo against a WIP nengo-bones branch).

What exactly does it mean to divide jobs into stages?

This is probably best explained in the TravisCI documentation https://docs.travis-ci.com/user/build-stages/

In the .nengobones.yml of Nengo, how do the script and env entries on the same indentation level interact?

script would override the value in env, if you manually specified a SCRIPT variable there as well.

In general, Nengo Bones is mainly intended for internal developer use, so it will likely never be as "polished" as our more user-facing projects. We will continue to work on the documentation, but again our apologies that you do not find it that helpful. However, if you have any other questions feel free to ask here or on the forums and I can try to answer them.

[jgosmann]

Each templated file has its own section, with name matching the filename (e.g. .travis.yml has a travis_yml section, .codecov.yml has the codecov_yml section, etc.). Is that what you mean about the hierarchical structure?

That, but also what the structure for each of those sections is (as they presumably not map 1:1 to the respective files)

This is probably best explained in the TravisCI documentation https://docs.travis-ci.com/user/build-stages/

Maybe this should be referenced in the documentation (it wasn't clear to me that this was a Travis CI feature).

[drasmuss]

That, but also what the structure for each of those sections is (as they presumably not map 1:1 to the respective files)

All of the options within each section should be described in the documentation, but let me know if any are missing and I'll fill them in.

Maybe this should be referenced in the documentation (it wasn't clear to me that this was a Travis CI feature).

Just to be clear, everything in that section is referring to TravisCI features (everything after this part)

Any other options set for a job will be passed directly on to the .travis.yml config for that job. This opens up a wide range of configuration options (see https://docs.travis-ci.com/ for more information). For example,

But I'll try to rewrite that section to emphasize that more explicitly when I get the chance.

[jgosmann]

All of the options within each section should be described in the documentation, but let me know if any are missing and I'll fill them in.

That might be true. Maybe it is more about the way its presented. I find that there is a lot of noise (e.g. contents of generated files) around the actual essential bits.