Docs and tests

In an inspired and original move, jq's docs are to be found in the docs folder.

Generating the docs requires a working Ruby setup, read on for how to get one. If you just want to document a feature that you've added and you don't want to figure out Ruby, then you can skip this section, and just edit the YAML file. If you make a pull request with something that at least smells like valid YAML, we'll figure it out (or, failing that, annoy you into installing Ruby and fixing it).

Installing Ruby and dependencies

The docs folder is a website built with Bonsai. To work on it, you'll need a working Ruby install (get one here). I'm using version 1.9.3 (rvm install 1.9.3). In theory it shouldn't matter, but Ruby is notorious for breaking backward compatibility.

To install the dependencies for the website, run bundle install from the docs folder.

rake build from the docs folder should now work (it generates a website in the output folder), and rake serve will start a mini webserver displaying the docs.

Editing the manual

When you add a new builtin or other feature, it should get an entry in the manual. The manual is found at docs/content/3.manual/manual.yml, and it's a big YAML file. The format is fairly straightforward, just find an entry documenting something vaguely similar to your new feature and use that as a template. Note that YAML is sensitive to indentation.

The manpage jq.1 is generated from the same source as the HTML manual (use "make jq.1" from the project root, you'll need a working Ruby as above), so you should stick to basic Markdown formatting in the manual. In particular, don't use raw HTML tags in manual.yml; they won't come out right in the manpage.

You'll notice that almost all manual entries have an examples section which look something like this:

        examples:
          - program: '.foo, .bar'
            input: '{"foo": 42, "bar": "something else", "baz": true}'
            output: ['42', '"something else"']

These are important. As well as docs, they're tests. In particular, be aware that program is a YAML string, input is a YAML string, and output is a YAML list of YAML strings.

Tests

As well as the examples section of the manual, there is a testsuite in the file testdata in the project root. There's no need to duplicate tests between the manual and testdata. The latter is for testing tricky edge-cases which are too fiddly to be useful examples in the manual, but need to be checked for correctness.

The testdata file format is particularly simple. Each testcase has the program on one line, the input on the next, and the output on the third. There may be multiple lines of output if the program produces multiple results. Testcases are separated by a blank line, and lines starting with # are ignored.

To run the tests, do make test from the project root. The tests are run under Valgrind (which you'll need to have installed), and make test will fail if any of the tests don't give the expected output, or if Valgrind reports that they leak memory or use it invalidly.