Add documentation about the website.

- Add a README with details on the differences with the official documentation,
  and instructions on how to use the generator.
- The front page of each FFmpeg version now includes the list of differences.
  Its content is taken from the README.md file.

Author: ayosec

.github/readme/badge.svg

@@ -1,23 +1,34 @@
 {
+  bigdecimal = {
+    groups = [ "default" ];
+    platforms = [ ];
+    source = {
+      remotes = [ "https://rubygems.org" ];
+      sha256 = "1gi7zqgmqwi5lizggs1jhc3zlwaqayy9rx2ah80sxy24bbnng558";
+      type = "gem";
+    };
+    version = "3.1.8";
+  };
   concurrent-ruby = {
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1qh1b14jwbbj242klkyz5fc7npd4j0mvndz62gajhvl1l3wd7zc2";
+      sha256 = "0chwfdq2a6kbj6xz9l6zrdfnyghnh32si82la1dnpa5h75ir5anl";
       type = "gem";
     };
-    version = "1.2.3";
+    version = "1.3.4";
   };
   google-protobuf = {
+    dependencies = [ "bigdecimal" "rake" ];
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1mnxzcq8kmyfb9bkzqnp019d1hx1vprip3yzdkkha6b3qz5rgg9r";
+      sha256 = "1d99vyhmyp2n5zd0qmfymzwbcn71dbnwwvc0m4z14msjb7b8dvf0";
       type = "gem";
     };
-    version = "3.25.3";
+    version = "4.28.3";
   };
   haml = {
     dependencies = [ "temple" "thor" "tilt" ];
@@ -35,62 +46,72 @@
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1kl9c3kdchjabrihdqfmcplk3lq4cw1rr9f378y6q22qwy5dndvs";
+      sha256 = "1q1f2sdw3y3y9mnym9dhjgsjr72sq975cfg5c4yx7gwv8nmzbvhk";
       type = "gem";
     };
-    version = "2.8.5";
+    version = "2.8.7";
   };
   nokogiri = {
     dependencies = [ "mini_portile2" "racc" ];
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "173zavvxlwyi48lfskk48wcrdbkvjlhjhvy4jpcrfx72rpjjx4k8";
+      sha256 = "15gysw8rassqgdq3kwgl4mhqmrgh7nk2qvrcqp4ijyqazgywn6gq";
       type = "gem";
     };
-    version = "1.16.2";
+    version = "1.16.7";
   };
   racc = {
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "01b9662zd2x9bp4rdjfid07h09zxj7kvn7f5fghbqhzc625ap1dp";
+      sha256 = "0byn0c9nkahsl93y9ln5bysq4j31q8xkf2ws42swighxd4lnjzsa";
       type = "gem";
     };
-    version = "1.7.3";
+    version = "1.8.1";
   };
   rake = {
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1ilr853hawi09626axx0mps4rkkmxcs54mapz9jnqvpnlwd3wsmy";
+      sha256 = "17850wcwkgi30p7yqh60960ypn7yibacjjha0av78zaxwvd3ijs6";
+      type = "gem";
+    };
+    version = "13.2.1";
+  };
+  redcarpet = {
+    groups = [ "default" ];
+    platforms = [ ];
+    source = {
+      remotes = [ "https://rubygems.org" ];
+      sha256 = "1sg9sbf9pm91l7lac7fs4silabyn0vflxwaa2x3lrzsm0ff8ilca";
       type = "gem";
     };
-    version = "13.1.0";
+    version = "3.6.0";
   };
   rouge = {
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1fkfa0iq3r9b0zzrxpxha17avmyzci3kidzmfbf6fd1279mndpb0";
+      sha256 = "0r0b48945hakgy0y7lg6h1bb7pkfz8jqd0r6777f80ij3sansvbs";
       type = "gem";
     };
-    version = "4.2.0";
+    version = "4.4.0";
   };
   sass-embedded = {
     dependencies = [ "google-protobuf" "rake" ];
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1ccqqkmicqs2nbawyknb17qfafwqq0k6jxibcm86vqd1jp185pxa";
+      sha256 = "1xiszsk8j3vvj6dxrkvx7kn8adh24dq8kxxa6wlz8ns6mb3l2dib";
       type = "gem";
     };
-    version = "1.71.1";
+    version = "1.80.6";
   };
   temple = {
     groups = [ "default" ];
@@ -107,19 +128,19 @@
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "1vq1fjp45az9hfp6fxljhdrkv75cvbab1jfrwcw738pnsiqk8zps";
+      sha256 = "1nmymd86a0vb39pzj2cwv57avdrl6pl3lf5bsz58q594kqxjkw7f";
       type = "gem";
     };
-    version = "1.3.1";
+    version = "1.3.2";
   };
   tilt = {
     groups = [ "default" ];
     platforms = [ ];
     source = {
       remotes = [ "https://rubygems.org" ];
-      sha256 = "0p3l7v619hwfi781l3r7ypyv1l8hivp09r18kmkn6g11c4yr1pc2";
+      sha256 = "0kds7wkxmb038cwp6ravnwn8k65ixc68wpm8j5jx5bhx8ndg4x6z";
       type = "gem";
     };
-    version = "2.3.0";
+    version = "2.4.0";
   };
 }

.nix/gemset.nix

@@ -5,3 +5,4 @@ gem "nokogiri", "~> 1"
 gem "rouge", "~> 4.1"
 gem "sass-embedded", "~> 1"
 gem "concurrent-ruby", "~> 1.2"
+gem "redcarpet", "~> 3.6"

Gemfile

@@ -1,25 +1,29 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    concurrent-ruby (1.2.3)
-    google-protobuf (3.25.3)
+    bigdecimal (3.1.8)
+    concurrent-ruby (1.3.4)
+    google-protobuf (4.28.3)
+      bigdecimal
+      rake (>= 13)
     haml (6.3.0)
       temple (>= 0.8.2)
       thor
       tilt
-    mini_portile2 (2.8.5)
-    nokogiri (1.16.2)
+    mini_portile2 (2.8.7)
+    nokogiri (1.16.7)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    racc (1.7.3)
-    rake (13.1.0)
-    rouge (4.2.0)
-    sass-embedded (1.71.1)
-      google-protobuf (~> 3.25)
-      rake (>= 13.0.0)
+    racc (1.8.1)
+    rake (13.2.1)
+    redcarpet (3.6.0)
+    rouge (4.4.0)
+    sass-embedded (1.80.6)
+      google-protobuf (~> 4.28)
+      rake (>= 13)
     temple (0.10.3)
-    thor (1.3.1)
-    tilt (2.3.0)
+    thor (1.3.2)
+    tilt (2.4.0)
 
 PLATFORMS
   ruby
@@ -28,8 +32,9 @@ DEPENDENCIES
   concurrent-ruby (~> 1.2)
   haml (~> 6)
   nokogiri (~> 1)
+  redcarpet (~> 3.6)
   rouge (~> 4.1)
   sass-embedded (~> 1)
 
 BUNDLED WITH
-   2.5.5
+   2.5.16

Gemfile.lock

@@ -0,0 +1,97 @@
+# FFmpeg Filters Documentation
+
+The tool in this repository builds an alternative presentation of the
+[official documentation for FFmpeg filters][offdocs]. It aims to be easier
+to read and easier to navigate.
+
+[![Open Website](.github/readme/badge.svg)][website]
+
+<!-- differences -->
+
+## Differences with the Official Documentation
+
+* Each filter has its own dedicated page.
+
+* Filters are organized into groups (like *Filters / Audio*, or
+  *Sources / Multimedia*).
+
+    The groups are guessed from the section headers in the official
+    documentation.
+
+* All pages have a search box to jump to another filter.
+
+    It can be focused by pressing the key <kbd>/</kbd>, and then use arrows
+    (<kbd>↓</kbd>, <kbd>↑</kbd>) to select one of the results.
+
+    The filter's description in the search results is the first sentence of its
+    documentation.
+
+* Many code snippets are rendered with syntax highlighting.
+
+    <!-- [highlight] This is an example from the filter:overlay filter:
+
+        ffmpeg -i left.avi -i right.avi -filter_complex "
+        nullsrc=size=200x100 [background];
+        [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
+        [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
+        [background][left]       overlay=shortest=1       [background+left];
+        [background+left][right] overlay=shortest=1:x=100 [left+right]
+        "
+    -->
+
+    The highlighting is inferred from the content, so it may not work in some
+    cases. The official documentation does not specify the language in which the
+    snippets are written.
+
+* Responsive design for smaller screens.
+
+* Dark and light themes.
+
+* Documentation for all _major.minor_ versions, under *Other Vers.* in the sidebar.
+
+    This is helpful when you have to use an older version of FFmpeg.
+
+* The *Version Matrix* shows which filters are available in each FFmpeg version.
+
+<!-- end differences -->
+
+## Usage
+
+The documentation can be [read in GitHub Pages][website], and it is possible to
+build it locally.
+
+### Nix Flakes
+
+The recommended way to run the generator is with [`nix run`][nix-run]:
+
+```console
+$ nix run github:ayosec/ffmpeg-filters-docs
+```
+
+The tool accepts some command-line arguments (see `--help`). For example, to
+build only the documentation for FFmpeg 7.1 in the path `/tmp/ffdocs`:
+
+```console
+$ nix run github:ayosec/ffmpeg-filters-docs -- --versions 7.1 --output /tmp/ffdocs
+```
+
+To execute the tool from a copy of this repository:
+
+```console
+$ nix develop --command ./ffmpeg-filters-docs […]
+```
+
+### Docker
+
+A Docker image can be built with the file [`docker/Dockerfile`](./docker/Dockerfile).
+
+```console
+$ docker build --tag ffdocs --file docker/Dockerfile .
+
+$ docker run --volume /tmp/web:/tmp/web ffdocs --versions 7.1 --output /tmp/web
+```
+
+
+[offdocs]: https://ffmpeg.org/ffmpeg-filters.html
+[website]: https://ayosec.github.io/ffmpeg-filters-docs/
+[nix-run]: https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-run.html

README.md

@@ -64,7 +64,7 @@
           installPhase = ''
             mkdir -p "$out"/{source,bin}
 
-            cp -a "${bin-name}" lib "$out/source"
+            cp -a "${bin-name}" README.md lib "$out/source"
 
             bin="$out/bin/${bin-name}"
 

flake.nix

@@ -25,10 +25,7 @@ def process(doc)
     private def stylize_code_blocks(doc)
       doc.search("pre").each do |elem|
         code = elem.inner_text.strip
-        if lexer = guess_lexer(code)
-          formatter = Rouge::Formatters::HTMLInline.new(Rouge::Themes::Github.new)
-          result = formatter.format(lexer.lex(code))
-
+        if result = SyntaxHighlight.highlight(code)
           # Replace <pre> with the generated HTML.
           elem.set_attribute("data-source", code)
           elem.inner_html = Nokogiri::HTML5.fragment(result)
@@ -38,16 +35,25 @@ def process(doc)
       doc
     end
 
-    private def guess_lexer(code)
-      case code.lstrip
-      when /\A__kernel/
-        Rouge::Lexers::C.new
-      when %r{\A#!.*/sh}, /\Aecho /
-        Rouge::Lexers::Shell.new
-      when /\A(-i|ffplay|ffmpeg|ffprobe)/, /\A(#.+\n)*(\.\/)?(ffplay|ffmpeg|ffprobe)/
-        CodeExamplesLexer.new
-      when /\A(\[(\w|-)+\]|\w+=)/, /\A\w+\[\w\]/
-        CodeExamplesLexer.new :filtergraph
+    module SyntaxHighlight
+      def self.highlight(code)
+        if lexer = guess_lexer(code)
+          formatter = Rouge::Formatters::HTMLInline.new(Rouge::Themes::Github.new)
+          formatter.format(lexer.lex(code))
+        end
+      end
+
+      def self.guess_lexer(code)
+        case code.lstrip
+        when /\A__kernel/
+          Rouge::Lexers::C.new
+        when %r{\A#!.*/sh}, /\Aecho /
+          Rouge::Lexers::Shell.new
+        when /\A(-i|ffplay|ffmpeg|ffprobe)/, /\A(#.+\n)*(\.\/)?(ffplay|ffmpeg|ffprobe)/
+          CodeExamplesLexer.new
+        when /\A(\[(\w|-)+\]|\w+=)/, /\A\w+\[\w\]/
+          CodeExamplesLexer.new :filtergraph
+        end
       end
     end