Add docs-resources pdf theme, IDL highlighting (#10)

* Add riscv pdf template, IDL syntax highlighting

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "ext/riscv-opcodes"]
 	path = ext/riscv-opcodes
 	url = https://github.com/riscv/riscv-opcodes.git
+[submodule "ext/docs-resources"]
+	path = ext/docs-resources
+	url = https://github.com/riscv/docs-resources.git

Gemfile

@@ -5,14 +5,14 @@ ruby "3.2.3"
 source "https://rubygems.org"
 
 gem "asciidoctor-diagram", "~> 2.2"
-gem "asciidoctor-multipage"
 gem "asciidoctor-pdf"
 gem "base64"
 gem "bigdecimal"
 gem "json_schemer", "~> 1.0"
 gem "minitest"
+gem "pygments.rb"
 gem "rake", "~> 13.0"
-gem "slim", "~> 5.1"
+gem "rouge"
 gem "treetop", "1.6.12"
 gem "webrick"
 gem "yard"

Gemfile.lock

@@ -15,8 +15,6 @@ GEM
     asciidoctor-diagram-ditaamini (1.0.3)
     asciidoctor-diagram-plantuml (1.2024.5)
       asciidoctor-diagram-batik (~> 1.17)
-    asciidoctor-multipage (0.0.19)
-      asciidoctor (>= 2.0.11, < 2.1)
     asciidoctor-pdf (2.3.14)
       asciidoctor (~> 2.0)
       concurrent-ruby (~> 1.1)
@@ -82,6 +80,7 @@ GEM
       pdf-reader (~> 2.0)
       prawn (~> 2.2)
     public_suffix (6.0.0)
+    pygments.rb (3.0.0)
     racc (1.8.0)
     rainbow (3.1.1)
     rake (13.2.1)
@@ -91,6 +90,7 @@ GEM
       nokogiri
     rexml (3.2.8)
       strscan (>= 3.0.9)
+    rouge (4.3.0)
     rubocop (1.64.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -111,9 +111,6 @@ GEM
     ruby-progressbar (1.13.0)
     ruby-rc4 (0.1.5)
     simpleidn (0.2.3)
-    slim (5.2.1)
-      temple (~> 0.10.0)
-      tilt (>= 2.1.0)
     solargraph (0.50.0)
       backport (~> 1.2)
       benchmark
@@ -131,7 +128,6 @@ GEM
       tilt (~> 2.0)
       yard (~> 0.9, >= 0.9.24)
     strscan (3.1.0)
-    temple (0.10.3)
     thor (1.3.1)
     tilt (2.3.0)
     treetop (1.6.12)
@@ -147,16 +143,16 @@ PLATFORMS
 
 DEPENDENCIES
   asciidoctor-diagram (~> 2.2)
-  asciidoctor-multipage
   asciidoctor-pdf
   base64
   bigdecimal
   json_schemer (~> 1.0)
   minitest
+  pygments.rb
   rake (~> 13.0)
+  rouge
   rubocop-minitest
   ruby-prof
-  slim (~> 5.1)
   solargraph
   treetop (= 1.6.12)
   webrick

arch/ext/Zbs.yaml

@@ -9,10 +9,14 @@ Zbs:
   company:
     name: RISC-V International
     url: https://riscv.org
+  doc_license:
+    name: Creative Commons Attribution 4.0 International License (CC-BY 4.0)
+    url: https://creativecommons.org/licenses/by/4.0/
   versions:
   - version: 1.0
     state: ratified
     ratification_date: 2021-06
+    url: https://drive.google.com/drive/u/0/folders/1_wqb-rXOVkGa6rqmugN3kwCftWDf1daU
     repositories:
       - url: https://github.com/riscv/riscv-bitmanip
         branch: main

backends/ext_pdf_doc/idl_lexer.rb

@@ -0,0 +1,59 @@
+require "rouge"
+
+module Rouge
+  module Lexers
+    class Idl < RegexLexer
+      tag "idl"
+      filenames "idl", "isa"
+
+      title "IDL"
+      desc "ISA Description Language"
+
+      ws = /[ \n]+/
+      id = /[a-zA-Z_][a-zA-Z0-9_]*/
+
+      def self.keywords
+        @keywords ||= Set.new %w[
+          if else for return returns arguments description body function builtin enum bitfield
+        ]
+      end
+
+      def self.keywords_type
+        @keywords_type ||= Set.new %w[
+          Bits XReg U32 U64 String Boolean
+        ]
+      end
+
+      # start { push :bol }
+
+      state :bol do
+        rule(//) { pop! }
+      end
+
+      state :root do
+        rule ws, Text::Whitespace
+        rule %r{#.*}, Comment::Single
+        rule %r{"[^"]*"}, Str::Double
+        rule %r{[A-Z][a-zA-Z0-9]*}, Name::Constant
+        rule %r{(?:(?:[0-9]+)|(?:XLEN))?'s?[bodh]?[0-9_a-fA-F]+}, Num
+        rule %r/0x[0-9a-f]+[lu]*/i, Num::Hex
+        rule %r/0[0-7]+[lu]*/i, Num::Oct
+        rule %r{\d+}, Num::Integer
+        rule %r{(?:true|false|\$encoding|\$pc)}, Name::Builtin
+        rule %r{[.,;:\[\]\(\)\}\{]}, Punctuation
+        rule %r([~!%^&*+=\|?:<>/-]), Operator
+        rule id do |m|
+          name = m[0]
+
+          if self.class.keywords.include? name
+            token Keyword
+          elsif self.class.keywords_type.include? name
+            token Keyword::Type
+          else
+            token Name
+          end
+        end
+      end
+    end
+  end
+end

backends/ext_pdf_doc/tasks.rake

@@ -48,10 +48,15 @@ module AsciidocUtils
   end
 end
 
+file "#{$root}/ext/docs-resources/themes/riscv-pdf.yml" => "#{$root}/.gitmodules" do |t|
+  system "git submodule update --init ext/docs-resources"
+end
+
 rule %r{#{$root}/gen/ext_pdf_doc/.*/pdf/.*_extension\.pdf} => proc { |tname|
   config_name = Pathname.new(tname).relative_path_from("#{$root}/gen/ext_pdf_doc").to_s.split("/")[0]
   ext_name = Pathname.new(tname).basename(".pdf").to_s.split("_")[0..-2].join("_")
   [
+    "#{$root}/ext/docs-resources/themes/riscv-pdf.yml",
     "#{$root}/gen/ext_pdf_doc/#{config_name}/adoc/#{ext_name}_extension.adoc"
   ]
 } do |t|
@@ -60,7 +65,20 @@ rule %r{#{$root}/gen/ext_pdf_doc/.*/pdf/.*_extension\.pdf} => proc { |tname|
   adoc_file = "#{$root}/gen/ext_pdf_doc/#{config_name}/adoc/#{ext_name}_extension.adoc"
 
   FileUtils.mkdir_p File.dirname(t.name)
-  Asciidoctor.convert_file(adoc_file, backend: "pdf", safe: :safe, to_file: t.name)
+  sh [
+    "asciidoctor-pdf",
+    "-w",
+    "-v",
+    "-a toc",
+    "-a compress",
+    "-a pdf-theme=#{$root}/ext/docs-resources/themes/riscv-pdf.yml",
+    "-a pdf-fontsdir=#{$root}/ext/docs-resources/fonts",
+    "-a imagesdir=#{$root}/ext/docs-resources/images",
+    "-r asciidoctor-diagram",
+    "-r #{$root}/backends/ext_pdf_doc/idl_lexer",
+    "-o #{t.name}",
+    adoc_file
+  ].join(" ")
 
   puts
   puts "Success!! File written to #{t.name}"
@@ -102,6 +120,8 @@ rule %r{#{$root}/gen/ext_pdf_doc/.*/adoc/.*_extension\.adoc} => proc { |tname|
   erb.filename = template_path.to_s
 
   ext = arch_def.extension(ext_name)
+  version_num = ENV.key?("EXT_VERSION") ? ENV["EXT_VERSION"] : ext.versions.sort { |v| Gem::Version.new(v["version"]) }.last["version"]
+  ext_version = ext.versions.find { |v| v["version"] == version_num }
   FileUtils.mkdir_p File.dirname(t.name)
   File.write t.name, AsciidocUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
 end
@@ -120,6 +140,8 @@ namespace :gen do
 
   desc <<~DESC
     Generate PDF documentation for :extension that is defined or overlayed in :cfg
+
+    The latest version will be used, but can be overloaded by setting the EXT_VERSION environment variable.
   DESC
   task :cfg_ext_pdf, [:extension, :cfg] do |_t, args|
     raise ArgumentError, "Missing required argument :extension" if args[:extension].nil?