Use git version of ocaml-pandoc for now. (#3532)

Author: smimram

.github/scripts/build-doc.sh

@@ -7,6 +7,6 @@ eval "$(opam config env)"
 OCAMLPATH="$(cat ../.ocamlpath)"
 export OCAMLPATH
 
-opam install -y odoc pandoc-include
+opam install -y odoc
 dune build @doc
 dune build --profile release ./src/js/interactive_js.bc.js

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: "3.x"
@@ -73,17 +73,22 @@ jobs:
           git remote set-url origin https://github.com/savonet/liquidsoap.git
           git fetch origin ${{ github.sha }}
           git checkout ${{ github.sha }}
+      - name: Install pandoc
+        run: |
+          cd /tmp
+          git clone https://github.com/smimram/ocaml-pandoc.git
+          opam pin -y add ocaml-pandoc
       - name: Build
         run: |
           echo "::group::Preparing build"
           cd /tmp/liquidsoap-full
           git remote set-url origin https://github.com/savonet/liquidsoap-full.git
-          git fetch --recurse-submodules=no && git checkout origin/master -- Makefile.git
+          git fetch --recurse-submodules=no
+          git checkout origin/master -- Makefile.git
           make public
           git reset --hard
           git pull
           cp PACKAGES.minimal PACKAGES
-          eval $(opam env)
           opam pin -yn .
           opam info -f "depopts:" liquidsoap-core | grep -v osx-secure-transport | xargs opam remove --force -y ffmpeg-avutil cohttp-lwt-unix prometheus-app ${{ needs.build_details.outputs.minimal_exclude_deps }}
           echo "::endgroup::"
@@ -180,6 +185,11 @@ jobs:
         run: |
           apt-get update
           apt-get install -y npm
+      - name: Install pandoc
+        run: |
+          cd /tmp
+          sudo -u opam -E git clone https://github.com/smimram/ocaml-pandoc.git
+          sudo -u opam -E opam pin -y add ocaml-pandoc
       - name: Build doc
         env:
           CPU_CORES: ${{ steps.cpu_cores.outputs.count }}
@@ -235,6 +245,15 @@ jobs:
           sudo -u opam -E git remote set-url origin https://github.com/savonet/liquidsoap.git
           sudo -u opam -E git fetch origin ${{ github.sha }}
           sudo -u opam -E git checkout ${{ github.sha }}
+      - name: Install pandoc
+        run: |
+          cd /tmp
+          if [ ! -d ocaml-pandoc ]; then
+            mkdir -p ocaml-pandoc;
+            chown -R opam ocaml-pandoc;
+            sudo -u opam -E git clone https://github.com/smimram/ocaml-pandoc.git ocaml-pandoc
+          fi
+          sudo -u opam -E opam pin -y add ocaml-pandoc
       - name: Build
         env:
           CPU_CORES: ${{ steps.cpu_cores.outputs.count }}
@@ -251,8 +270,8 @@ jobs:
       - name: Install additional packages
         if: matrix.target == '@doctest'
         run: |
-          sudo apt-get -y update
-          sudo apt-get -y install frei0r-plugins
+          apt-get -y update
+          apt-get -y install frei0r-plugins
           sudo -u opam -E opam install -y prometheus-liquidsoap
       - name: Run tests
         env:
@@ -380,6 +399,11 @@ jobs:
         if: matrix.os == 'alpine'
         run: |
           apk -U --force-overwrite upgrade
+      - name: Install pandoc
+        run: |
+          cd /tmp
+          sudo -u opam -E git clone https://github.com/smimram/ocaml-pandoc.git ocaml-pandoc
+          sudo -u opam -E opam pin -y add ocaml-pandoc
       - name: Build
         run: |
           cd /tmp/liquidsoap-full/liquidsoap

doc/Makefile

@@ -6,7 +6,7 @@ all: dune
 test: dune
 	@for i in $(MD); do \
 	echo -n "Compiling $$i... "; \
-	pandoc --filter=pandoc-include --metadata title="bla" --template=template.html $$i -o /tmp/`basename $$i .md`.html; \
+	pandoc $$i -t json | pandoc-include --directory "content/liq" | pandoc -f json --metadata title="bla" --template=template.html -o /tmp/`basename $$i .md`.html; \
 	echo "done"; \
 	done
 	@dune build @doctest

doc/content/beets.md

@@ -75,7 +75,7 @@ We rely on `request.dynamic` to call `beet random`
 (with `-f '$path'` option so beets only returns the matching track's path)
 every time the source must prepare a new track:
 
-```{.liquidsoap include="content/liq/beets-source.liq" from=1 to=-1}
+```{.liquidsoap include="beets-source.liq" from="BEGIN" to="END"}
 
 ```
 
@@ -101,7 +101,7 @@ import:
 
 Then we only need to add `amplify` to our source creation function. In the example below we also add `blank.eat`, to automatically cut silence at the beginning or end of tracks.
 
-```{.liquidsoap include="content/liq/beets-amplify.liq" from=1}
+```{.liquidsoap include="beets-amplify.liq" from="BEGIN"}
 
 ```
 
@@ -117,7 +117,7 @@ In that case,
 the list of paths returned by `beet random -f '$path'` fits directly
 what's needed by protocol resolution:
 
-```{.liquidsoap include="content/liq/beets-protocol.liq" from=1}
+```{.liquidsoap include="beets-protocol.liq" from="BEGIN"}
 
 ```
 

doc/content/blank.md

@@ -23,7 +23,7 @@ listeners get some silence again. To avoid that problem we made the
 (i.e. declare it as unavailable), which perfectly suits the typical setup used
 for live shows:
 
-```{.liquidsoap include="content/liq/blank-sorry.liq"}
+```{.liquidsoap include="blank-sorry.liq"}
 
 ```
 
@@ -33,6 +33,6 @@ more about liquidsoap's notion of [source](sources.html).
 Finally, if you need to do some custom action when there's too much blank, we
 have `blank.detect`:
 
-```{.liquidsoap include="content/liq/blank-detect.liq" from=1 to=-1}
+```{.liquidsoap include="blank-detect.liq" from=1 to=-1}
 
 ```

doc/content/complete_case.md

@@ -15,7 +15,7 @@ Once you've managed to describe what you want in such a modular way, you're half
 
 Now here is how to write that in [Liquidsoap](index.html).
 
-```{.liquidsoap include="content/liq/complete-case.liq"}
+```{.liquidsoap include="complete-case.liq"}
 
 ```
 

doc/content/cookbook.md

@@ -48,7 +48,7 @@ When building your stream, you'll often need to make it unfallible. Usually, you
 
 [Liquidsoap](index.html) can achieve basic streaming tasks like transcoding with ease. You input any number of "source" streams using `input.http`, and then transcode them to any number of formats / bitrates / etc. The only limitation is your hardware: encoding and decoding are both heavy on CPU. If you want to get the best use of CPUs (multicore, memory footprint etc.) when encoding media with Liquidsoap, we recommend using the `%ffmpeg` encoders.
 
-```{.liquidsoap include="content/liq/transcoding.liq"}
+```{.liquidsoap include="transcoding.liq"}
 
 ```
 
@@ -64,15 +64,15 @@ to encode the file as quickly as possible.
 Finally, we use the `on_stop` handler to shutdown
 liquidsoap when streaming is finished.
 
-```{.liquidsoap include="content/liq/re-encode.liq"}
+```{.liquidsoap include="re-encode.liq"}
 
 ```
 
 ## RTMP server
 
 With our [FFmpeg support](ffmpeg.html), it is possible to create a simple RTMP server with no re-encoding:
 
-```{.liquidsoap include="content/liq/rtmp.liq"}
+```{.liquidsoap include="rtmp.liq"}
 
 ```
 
@@ -83,23 +83,23 @@ the SRT transport protocol:
 
 Sender:
 
-```{.liquidsoap include="content/liq/srt-sender.liq" from=1}
+```{.liquidsoap include="srt-sender.liq" from="BEGIN"}
 
 ```
 
 Receiver:
 
-```{.liquidsoap include="content/liq/srt-receiver.liq" to=-1}
+```{.liquidsoap include="srt-receiver.liq" to="END"}
 
 ```
 
 ## Scheduling
 
-```{.liquidsoap include="content/liq/fallback.liq" to=-1}
+```{.liquidsoap include="fallback.liq" to="END"}
 
 ```
 
-```{.liquidsoap include="content/liq/scheduling.liq" from=1 to=-1}
+```{.liquidsoap include="scheduling.liq" from="BEGIN" to="END"}
 
 ```
 
@@ -114,7 +114,7 @@ stored to avoid reindexing at each run). The resulting object can then
 be queried with the `find` method in order to return all files matching the given
 conditions and thus generate a playlist:
 
-```{.liquidsoap include="content/liq/medialib.liq"}
+```{.liquidsoap include="medialib.liq"}
 
 ```
 
@@ -160,7 +160,7 @@ It can be useful to have a special playlist that is played at least every 20 min
 You may think of a promotional playlist for instance.
 Here is the recipe:
 
-```{.liquidsoap include="content/liq/regular.liq" from=1 to=-1}
+```{.liquidsoap include="regular.liq" from="BEGIN" to="END"}
 
 ```
 
@@ -277,7 +277,7 @@ to add an extra `5s` of silence when transitioning out of a live `input.harbor`
 
 This can be done with the `append` operator:
 
-```{.liquidsoap include="content/liq/append-silence.liq" to=-1}
+```{.liquidsoap include="append-silence.liq" to="END"}
 
 ```
 
@@ -287,14 +287,14 @@ It is sometimes useful (or even legally necessary) to keep a backup of an audio
 stream. Storing all the stream in one file can be very impractical. In order to
 save a file per hour in wav format, the following script can be used:
 
-```{.liquidsoap include="content/liq/dump-hourly.liq" from=1}
+```{.liquidsoap include="dump-hourly.liq" from="BEGIN"}
 
 ```
 
 In the following variant we write a new mp3 file each time new metadata is
 coming from `s`:
 
-```{.liquidsoap include="content/liq/dump-hourly2.liq" from=1}
+```{.liquidsoap include="dump-hourly2.liq" from="BEGIN"}
 
 ```
 
@@ -332,7 +332,7 @@ Crossfade-based transitions are more complex and involve buffering source data i
 
 We provide a default operator named `cross.smart` which may be suitable for most usage. But you can also create your own customized crossfade transitions. This is in particular true if you are expecting crossfade transitions between tracks of your `music` source but not between a `music` track and e.g. some jingles. Here's how to do it in this case:
 
-```{.liquidsoap include="content/liq/cross.smart.liq" from=1 to=-1}
+```{.liquidsoap include="cross.smart.liq" from="BEGIN" to="END"}
 
 ```
 
@@ -356,7 +356,7 @@ Could not set buffer size to 'frame.size' (1920 samples), got 2048.
 
 The solution is then to set liquidsoap's internal frame size to this value, which is most likely specific to your hardware. Let's try this script:
 
-```{.liquidsoap include="content/liq/frame-size.liq"}
+```{.liquidsoap include="frame-size.liq"}
 
 ```
 

doc/content/crossfade.md

@@ -19,7 +19,7 @@ You can find its documentation in the [language reference](reference.html).
 
 Liquidsoap also includes a ready-to-use operator defined using `cross`, it is called `crossfade` and is defined in the pervasive helper script `utils.liq`. Its code is:
 
-```{.liquidsoap include="content/liq/crossfade.liq"}
+```{.liquidsoap include="crossfade.liq"}
 
 ```
 

doc/content/dynamic_sources.md

@@ -14,7 +14,7 @@ a dynamic restreaming platform.
 
 Here's the code:
 
-```{.liquidsoap include="content/liq/dynamic-source.liq"}
+```{.liquidsoap include="dynamic-source.liq"}
 
 ```
 

doc/content/external_decoders.md

@@ -79,13 +79,13 @@ The flac decoder uses the `flac` command line. It is enabled if the binary can b
 
 Its code is the following:
 
-```{.liquidsoap include="content/liq/decoder-flac.liq"}
+```{.liquidsoap include="decoder-flac.liq"}
 
 ```
 
 Additionally, a metadata resolver is registered when the `metaflac` command can be found in the `$PATH`:
 
-```{.liquidsoap include="content/liq/decoder-metaflac.liq"}
+```{.liquidsoap include="decoder-metaflac.liq"}
 
 ```
 
@@ -98,6 +98,6 @@ registered using `decoder.oblivious.add`.
 
 Its code is the following:
 
-```{.liquidsoap include="content/liq/decoder-faad.liq"}
+```{.liquidsoap include="decoder-faad.liq"}
 
 ```

doc/content/external_encoders.md

@@ -53,6 +53,6 @@ Videos can also be encoded by programs able to read files in avi format from
 standard input. To use it, the flag `video=true` of `%external` should be
 used. For instance, a compressed avi file can be generated with `ffmpeg` using
 
-```{.liquidsoap include="content/liq/external-output.file.liq" from=1}
+```{.liquidsoap include="external-output.file.liq" from="BEGIN"}
 
 ```

doc/content/external_streams.md

@@ -30,6 +30,6 @@ run the external program.
 A wrapper, `input.mplayer`, is defined to use mplayer as the external decoder.
 Its code is:
 
-```{.liquidsoap include="content/liq/input.mplayer.liq"}
+```{.liquidsoap include="input.mplayer.liq"}
 
 ```

doc/content/ffmpeg_cookbook.md

@@ -6,7 +6,7 @@ Here are some examples of what is possible to do with the ffmpeg support in liqu
 
 With ffmpeg support, Liquidsoap can relay encoded streams without re-encoding them, making it possible to re-send a stream to multiple destinations. Here's an example:
 
-```{.liquidsoap include="content/liq/ffmpeg-relay.liq"}
+```{.liquidsoap include="ffmpeg-relay.liq"}
 
 ```
 
@@ -25,7 +25,7 @@ In the script below, you need to match the encoded format of the stream with a b
 The `output.harbor` will then relay the data from the file if no one is connected and start/stop the underlying
 input when there are listeners:
 
-```{.liquidsoap include="content/liq/ffmpeg-relay-ondemand.liq"}
+```{.liquidsoap include="ffmpeg-relay-ondemand.liq"}
 
 ```
 
@@ -34,15 +34,15 @@ input when there are listeners:
 Liquidsoap can also encode in one place and share the encoded with data with multiple outputs, making it possible to
 minimize CPU resources. Here's an example adapted from the previous one:
 
-```{.liquidsoap include="content/liq/ffmpeg-shared-encoding.liq"}
+```{.liquidsoap include="ffmpeg-shared-encoding.liq"}
 
 ```
 
 Shared encoding is even more useful when dealing with video encoding, which is very costly. Here's a fun example
 sharing audio and video encoding and sending to different destinations, both via Icecast and to YouTube/Facebook
 via the rtmp protocol:
 
-```{.liquidsoap include="content/liq/ffmpeg-shared-encoding-rtmp.liq"}
+```{.liquidsoap include="ffmpeg-shared-encoding-rtmp.liq"}
 
 ```
 
@@ -63,7 +63,7 @@ to adapt the binary data and, it's possible some new filters will need to be wri
 
 Here's a use case that has been tested: live switch between a playlist of mp4 files and a rtmp flv input:
 
-```{.liquidsoap include="content/liq/live-switch.liq"}
+```{.liquidsoap include="live-switch.liq"}
 
 ```