jq icon indicating copy to clipboard operation
jq copied to clipboard

Generate docs from Markdown with Pandoc

Open 01mf02 opened this issue 4 months ago • 0 comments

This PR changes the format of the user manual from YAML to Markdown. This gives a multitude of benefits, including better editor support, smaller files, better tooling, and more flexible document structure. The idea is that manuals for old jq versions (1.3 to 1.7) remain untouched as YAML, whereas new documentation is written in Markdown (docs/content/manual/manual.md). When new features are added to jq, they can be documented in the manual with a compatibility note, which should allow to document all future jq versions in one file.

I've tried to preserve the look as much as possible, but there are still a few aesthetic differences compared to the current manual, especially concerning the styling of examples. If these are important to you, I can try to make them more similar.

A preview of the current state:

Screenshot 2024-09-30 at 17-26-31 jq Manual

What works:

  • Manpage generation
  • Test generation from manual (man.test, manonig.test)
  • Table of contents generation
  • Search index generation
  • Links to jq-play.org for running examples

What does not work:

  • Automatic detection of Pandoc to build documentation: I am not autotools wizard, so I changed documentation building by default to false. That means you need to run ./configure --enable-docs even if you have all required dependencies (i.e. Pandoc).

01mf02 avatar Sep 30 '24 16:09 01mf02