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