Generate docs from Markdown with Pandoc

.github/workflows/manpage.yml

@@ -21,27 +21,18 @@ jobs:
  steps:
  - name: Checkout code
  uses: actions/checkout@v4
- - name: Setup Python
- uses: actions/setup-python@v5
+ - name: Install Pandoc
+ uses: pandoc/actions/setup@main
  with:
- python-version: '3.11'
- cache: pipenv
- - name: Install pipenv
- run: pip install pipenv
- - name: Install dependencies
- run: pipenv sync
- working-directory: docs
- - name: Validate manual schema
- run: pipenv run python3 validate_manual_schema.py content/manual/**/*.yml
- working-directory: docs
+ version: 3.4
  - name: Configure
  run: |
  autoreconf -i
  ./configure --enable-docs
  - name: Build man page, man.test, manonig.test
  run: |
  mv jq.1.prebuilt jq.1.old
- rm -f tests/man.test manonig.test
+ rm -f tests/man.test tests/manonig.test
  make jq.1.prebuilt tests/man.test tests/manonig.test
  - name: Make sure that jq.1.prebuilt, man.test, manonig.test are up to date
  run: |

.github/workflows/website.yml

@@ -17,6 +17,10 @@ jobs:
  uses: actions/checkout@v4
  with:
  fetch-depth: 0
+ - name: Install Pandoc
+ uses: pandoc/actions/setup@main
+ with:
+ version: 3.4
  - name: Setup Python
  uses: actions/setup-python@v5
  with:

Makefile.am

@@ -160,11 +160,9 @@ check_DATA = tests/man.test
 # Making changes to the manpage without having the python deps means your
 # tests won't run. If you aren't making changes to the examples, you probably
 # don't care. But if you are, then you need to run the tests anyway.
-tests/man.test tests/manonig.test: $(srcdir)/docs/content/manual/dev/manual.yml
+tests/man.test tests/manonig.test: $(srcdir)/docs/content/manual/manual.md
 if ENABLE_DOCS
- $(AM_V_GEN) ( cd ${abs_srcdir}/docs && \
- $(PIPENV) run python validate_manual_schema.py content/manual/dev/manual.yml && \
- $(PIPENV) run python build_mantests.py )
+ $(AM_V_GEN) ( cd ${abs_srcdir}/docs && ./build_mantests.sh )
 else
  @echo Changes to the manual.yml require docs to be enabled to update the manual test.
  @echo As a result, the manual test is out of date.
@@ -176,11 +174,9 @@ endif
 # manpage, then we'll end up using the cached version. Otherwise, we need to
 # rebuild it.
 man_MANS = jq.1
-jq.1.prebuilt: $(srcdir)/docs/content/manual/dev/manual.yml
+jq.1.prebuilt: $(srcdir)/docs/content/manual/manual.md
 if ENABLE_DOCS
- $(AM_V_GEN) ( cd ${abs_srcdir}/docs && \
- $(PIPENV) run python validate_manual_schema.py content/manual/dev/manual.yml && \
- $(PIPENV) run python build_manpage.py ) > $@
+ $(AM_V_GEN) ( cd ${abs_srcdir}/docs && ./build_manpage.sh ) > $@
 else
  @echo Changes to the manual.yml require docs to be enabled to update the manpage.
  @echo As a result, the manpage is out of date.
@@ -209,10 +205,10 @@ endif
 install-binaries: $(BUILT_SOURCES)
  $(MAKE) $(AM_MAKEFLAGS) install-exec
 
-DOC_FILES = docs/content docs/public docs/templates   \
- docs/Pipfile docs/Pipfile.lock docs/build_manpage.py  \
- docs/build_mantests.py docs/build_website.py docs/README.md \
- docs/validate_manual_schema.py docs/manual_schema.yml
+DOC_FILES = docs/content docs/public docs/templates docs/filters \
+ docs/man docs/Pipfile docs/Pipfile.lock docs/build_manpage.sh \
+ docs/build_mantests.sh docs/build_website.py docs/README.md \
+ docs/build_manual.sh
 
 EXTRA_DIST = $(DOC_FILES) $(man_MANS) $(TESTS) $(TEST_LOG_COMPILER) \
  jq.1.prebuilt jq.spec src/lexer.c src/lexer.h src/parser.c \

configure.ac

@@ -69,9 +69,9 @@ dnl Code coverage
 AC_ARG_ENABLE([gcov],
  AS_HELP_STRING([--enable-gcov],[enable gcov code coverage tool]))
 
-dnl Don't attempt to build docs if python deps aren't installed
+dnl Documentation
 AC_ARG_ENABLE([docs],
- AS_HELP_STRING([--disable-docs],[do not build docs]), [], [enable_docs=yes])
+ AS_HELP_STRING([--enable-docs],[build docs]))
 
 dnl Don't attempt to build the error injection object (if there is no LD_PRELOAD support)
 AC_ARG_ENABLE([error-injection],
@@ -81,31 +81,6 @@ dnl Enable building all static
 AC_ARG_ENABLE([all-static],
  AS_HELP_STRING([--enable-all-static],[link jq with static libraries only]))
 
-dnl find pipenv
-AC_ARG_VAR([PIPENV], [pipenv command])
-AC_CHECK_PROGS([PIPENV], pipenv)
-
-AS_IF([test "x$enable_docs" != "xno"],[
- AC_CACHE_CHECK([for Python dependencies], [jq_cv_python_deps],[
- jq_cv_python_deps=yes
- AS_IF([test "x$PIPENV" = "x" || \
- ! bmsg="`cd ${srcdir}/docs; LC_ALL=$LANG "$PIPENV" --venv`"],[
- jq_cv_python_deps=no
- ])
- ])
-
- AS_IF([test "x$jq_cv_python_deps" != "xyes"], [
- AC_MSG_WARN([Error checking python dependencies: $bmsg
-*****************************************************************
-* Python dependencies for building jq documentation not found. *
-* You can still build, install and hack on jq, but the manpage *
-* will not be rebuilt and new manpage tests will not be run. *
-* See docs/README.md for how to install the docs dependencies. *
-*****************************************************************])
- enable_docs=no
- ])
-])
-
 dnl Disable decNumber support
 AC_ARG_ENABLE([decnum],
  AS_HELP_STRING([--disable-decnum],[disable decnum support]))

docs/README.md

@@ -2,9 +2,11 @@ Documentation
 =============
 
 The jq website, manpages and some of the tests are generated from this
-directory. The manual is a YAML file in `content/manual`.
+directory. The manual is a Markdown file in `content/manual/manual.md`.
 
-To build the documentation (including building the jq manpage), you'll
+To build the jq manpage and the tests contained in it, you'll
+need `pandoc` (at least version 3.0).
+To build the website, you'll additionally
 need `python3` and `pipenv`. You can install `pipenv` like so:
 
  pip install pipenv

docs/build_manpage.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+pandoc man/prologue.md content/manual/manual.md man/epilogue.md -s --to=man --lua-filter filters/filter.lua