giblish 2.0.0.pre.alpha1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc5f7111b85423074f87986b2750ce3fa61dbf4364331a80481d0d5cc881673
-  data.tar.gz: 53fd77b1ac62eec70539e744950cfc8f121532f9639eb2bcb860d6142443474f
+  metadata.gz: 692017a96101341d60e2a0243d6b22441f75dab56904aa97a91f9c272e3c0630
+  data.tar.gz: f4e6e3bc7843484ee414b880ed562b8d94a49913f6637ee5a8c7233d56b99491
 SHA512:
-  metadata.gz: baa8d72424dc2cb581e90bf383849cb8043b13ca1aed2c5fe3a4b1d9a20aedccf69f6ac9936e7439ae1887074bf274a47553907bce1ce78decd68da207ca3b91
-  data.tar.gz: b579918b4aa8c68d0f9e1ac57a878e3279b3c8404e6f5e677e91859a6af45983feaca033bf051eff56ac7e4f45556f13faa5b79a7bbcb7fc47f18684b5fa952f
+  metadata.gz: 32186232754bfc2362c1ac18465747de784c8ce950226223bd67f342c0145cac91af6b0c6364a0c3b211cfba11367bc0959d08a01faf191d9f021f695231239f
+  data.tar.gz: b89358a5bb1945492ea14d0e74a42f9364da494a378911b84b062f632353b0350424b709da7d637d9c16095a778d8aa95a7a90a419376b02cb50e634b4b8e2a4

data/.github/workflows/unit_tests.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ["3.0", "3.1"]
+        ruby-version: ["2.7", "3.0", "3.1"]
 
     steps:
       - name: Install binutils
@@ -17,9 +17,9 @@ jobs:
           sudo apt -y install binutils
       - name: Install needed packages
         run: |
-          sudo apt-get -y install libpango1.0-dev graphviz
+          sudo apt-get -y install libpango1.0-dev graphviz libwebp-dev libzstd-dev
       - name: Checkout Giblish
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:

data/.gitignore

@@ -9,7 +9,6 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
-/.vscode/
 
 # Used by dotenv library to load environment variables.
 # .env

data/.ruby-version

@@ -1 +1 @@
-3.1.2
+3.1.3

data/Changelog.adoc

@@ -1,17 +1,42 @@
 = giblish changelog
+:docid: G-006
 
-== Not yet in place
+== Some of the things Not yet in place
 
+ * Investigate how to remove tmp/cache files and dirs during graph generation
  * Update docs for giblish.
- ** write detailed instructions on howto setup the doc generation examples
+ ** write instructions for github webhook triggered generation
  * Update the default css for giblish html generation.
+ * Implement a way for a user to customize the index page
+
+== v2.1.0
+
+Changes/New functionality::
+ * asciidoctor-diagram is required if it exists, this makes diagrams in documents render.
+ * giblish now complies with these precedence rules for document attributes:
+ .. An attribute passed to the API or CLI whose value does not end in @
+ .. (giblish specific) An attribute defined in an attribute provider for a specific source node
+ .. An attribute defined in the document
+ .. An attribute passed to the API or CLI whose value or name ends in @
+ .. (giblish specific) The default value set by giblish, if applicable
+ .. The default value set by asciidoctor, if applicable
++
+this is an augumentation of the ones found here: https://docs.asciidoctor.org/asciidoc/latest/attributes/assignment-precedence/
+
+== v2.0.0
+
+This is a breaking release because the internal dependencies to asciidoctor-pdf has been bumped from one major release to the next. `giblish` itself has not seen any major, internal, updates.
+
+Breaking changes::
+ * Dependency on asciidoctor-pdf has been bumped to v2.3
+ * rename some pdf attributes internally in giblish to comply with the new version of asciidoctor-pdf
 
 == v1.0.0
 
 This release includes a complete refactoring of almost the entire code base.
 
 Breaking changes::
- * The '-w' flag is removed  
+ * The '-w' flag is removed
  * The text search parameters interface has changed completely. A written specification of this interface is included in the docs.
  * The '-r' flag will, for html generation, *copy everything* under the given directory to the target location.
  ** the previous restriction on folder names has been removed.
@@ -36,7 +61,7 @@ Changes/New functionality::
  ** the implementation of the server-side search tools are written completely in ruby and does no longer depend on an external 'grep' tool.
  ** almost all needed infrastructure for implementing a server-side search script has been implemented within the 'giblish' gem.
  * The asciidoctor toolchain dependencies are updated to the latest versions (at the time of release).
- 
+
 
 == v0.8.0
 

data/README.adoc

@@ -1,11 +1,11 @@
 = giblish
 :docid: G-001
 :numbered:
+:toc: preamble
+:toclevels: 1
 
 image::https://github.com/rillbert/giblish/actions/workflows/unit_tests.yml/badge.svg["Build Status"]
 
-[abstract] 
-== Purpose
 
 giblish converts a source directory tree containing AsciiDoc files to a destination directory tree containing the corresponding html or pdf files. It adds some handy tools for easier navigation of the resulting destination tree.
 
@@ -23,11 +23,11 @@ IMPORTANT: The examples below are *not* the official documentation for the corre
 
 |Raspberry Pi documentation
 |https://www.rillbert.se/giblish_examples/rpi_docs/giblish_example/index.html[example]
-|The original documentation site uses Jekyl for site generation, the link points to a mirror where some small tweaks to the docs were made to make them suitable for generation with giblish.
+|The project's official documentation site uses Jekyl for site generation, the link points to a mirror where some small tweaks to the docs were made to make them suitable for generation with giblish.
 
 |The *old* asciidoctor docs
 |https://www.rillbert.se/giblish_examples/asciidoctor_docs/master/newindex.html[example]
-|An example of how giblish can generate the master branch of the official asciidoc.org documentation git repo can be found at
+|An example of how giblish can generate the master branch of the *old, deprecated* official asciidoc.org documentation git repo.
 
 |===
 
@@ -45,7 +45,9 @@ The features of giblish include:
 
 == Dependencies and credits
 
-Giblish uses the awesome *asciidoctor* and *asciidoctor-pdf* projects under the hood. Thank you @mojavelinux and others for making these brilliant tools available!!
+Giblish uses the awesome `asciidoctor` and `asciidoctor-pdf` projects under the hood. Thank you @mojavelinux and others for making these brilliant tools available!!
+
+The official documentation of these tools as well as extensive information about the AsciiDoc syntax can be found at https://docs.asciidoctor.org
 
 == Installation
 
@@ -107,7 +109,7 @@ Example document one::
 = Document one
 :toc:
 :numbered:
-:docid: G-001
+:docid: AB-001
 
 == Purpose
 
@@ -120,16 +122,16 @@ Example document two::
 = Document two
 :toc:
 :numbered:
-:docid: G-002
+:docid: AB-002
 
 == Purpose
 
-To illustrate the use of doc id. You can refer to document one as <<:docid:G-001>>. This will display a clickable link with the doc id (G-001 in this case).
+To illustrate the use of doc id. You can refer to document one as <<:docid:AB-001>>. This will display a clickable link with the doc id (AB-001 in this case).
 
 You can use the same syntax as the normal asciidoc cross-ref but replace 'xref' with ':docid:' as shown below:
 
- * <<:docid:G-002#purpose>> to refer to a specific section or anchor.
- * <<:docid:G-002#purpose,The purpose section>> to refer to a specific section and display a specific text for the link.
+ * <<:docid:AB-002#purpose>> to refer to a specific section or anchor.
+ * <<:docid:AB-002#purpose,The purpose section>> to refer to a specific section and display a specific text for the link.
 ----
 
 The above reference will work even if either document changes location or file name as long as both documents are parsed by giblish in the same run.

data/docs/howtos/{trigger_generation.adoc → setup_static_site.adoc}

@@ -1,5 +1,6 @@
-= Trigger document generation
-:imagesdir: trigger_generation_im
+= Setup a static website
+using giblish and git
+:imagesdir: setup_static_site_assets
 :numbered:
 :docid: G-003
 :toc: left
@@ -8,18 +9,18 @@
 
 To describe how to use `giblish` as a tool for creating a static web site backed by a git repo that is automatically generated each time a contributor push changes to the git repo.
 
-This text covers the followwing deployment scenarios:app-name: 
+This text covers the following deployment scenarios:
 
- . Using a git hook together with a simple (well) shell script
+ . Using a git hook together with a shell script.
  . Using a git hook together with Jenkins.
 
-They have been tested on Linux servers (Ubuntu). Most of the tools and scripts should work on a Windows server as well but might need some tweaking and is, again, not tested.
+They have been tested on Linux servers (Ubuntu). Most of the tools and scripts should work on a Windows server as well but might need some tweaking and it is not tested.
 
 If you want to dive straight in and setup one of the scenarios below, jump to <<setup_instructions>>, otherwise read on for some examples and considerations.
 
 == Git hook and shell script
 
-This requires the least number of dependencies to work but is more limited.
+This requires the least number of external dependencies but is limited.
 
 .Deploy using git hook and shell script
 image::deploy_with_hooks.svg[]
@@ -30,13 +31,13 @@ A 'Main Repo'::
 The common (bare) git repo used by all content writers to push updates to. This repo shall be setup with a server-side hook (_post-receive_) that initiates the html generation and is triggered by each push to the repo.
 
 A 'Staging Repo'::
-A mirror of the _Main Repo_ that fulfills two functions:
+A mirror of the _Main Repo_ that fulfils two functions:
 
  . to provide a checked-out working tree with the source files (adoc files).
  . to provide a script that uses giblish to generate html documents and publish those docs to a location where a web server can access them.
 
-Web Server::
-Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (e.g under /var/www/... )
+A Web Server::
+Apache, Nginx or other web server that provides clients with HTML pages located somewhere on the file system on the server (e.g under /var/www/... )
 
 === Pros & Cons
 
@@ -48,7 +49,7 @@ Cons::
  * The hook and publish scripts provided with giblish runs synchronously at each push from a _Doc Writer_ to the _Main Repo_. The time it takes to generate the HTML docs from the adoc source will thus be added to each push to the _Main Repo_.
  * You need to manually setup the _Staging Repo_ on the server and this is a bit more 'hackish' than letting a build orchestrator tool implement a proper 'build' of your documents. You might for example end up with race conditions if two pushes to the _Main Repo_ are done close in time.
 
-=== Using a combination of Jenkins and git hook
+== Using a combination of Jenkins and git hook
 
 This setup adds a Jenkins (or similar build orchestrator) installation so it is more tools to setup but offer more flexibility and performance. It is also more robust and thus more 'production friendly'.
 
@@ -66,9 +67,9 @@ Jenkins instance::
 A running instance of Jenkins and one or more defined build jobs that use giblish to build the HTML documents.
 
 Web Server::
-Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (e.g under /var/www/... )
+Apache, Nginx or other web server that provides clients with HTML pages located somewhere on the file system on the server (e.g under /var/www/... )
 
-==== Pros & cons
+=== Pros & cons
 
 Pros::
  * Using Jenkins enables a lot of flexibility and scaleability. You can setup multiple Jenkins agents to increase performance, you can define many build jobs where each job builds either a particular branch from a particular git repo or many branches from one or many repos.
@@ -83,9 +84,9 @@ Follow the instructions below to get one of the above setups running on your ser
 
 === Some preliminary notes
 
-IMPORTANT: Setting up permissions and secure your setup from unwanted access is outside the scope of these instructions. You must understand and implement the proper user/groups/rules for your use case.
+IMPORTANT: Setting up permissions and secure your setup from unwanted access is outside the scope of these instructions. You must understand and implement the proper authentication rules for your use case.
 
-NOTE: git server side hooks are used in the instructions below. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc].
+git server side hooks are used in the instructions below. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc].
 
 [[common_setup]]
 === Initial setup
@@ -94,9 +95,9 @@ These steps are common to both deployment scenarios.
 
 giblish setup::
  . Install ruby on the _Server_ (a version no more than 18 months old)
- . Install giblish on the _Server_ using `gem install giblish`
+ . Install giblish on the _Server_. See e.g. <<:docid:G-001>>
 
-git and gitrepo setup::
+git and git repo setup::
  . Install git on the _Server_.
  . Setup the *bare* _Main Repo_ on the _Server_ by either.
  .. Copy a bare repo you already use to the _Server_ file system.
@@ -104,7 +105,7 @@ git and gitrepo setup::
 +
 NOTE: If you start with an empty, bare, _Main Repo_ on the _Server_, it is a good idea to directly clone it to your local machine, commit some content to the 'master' branch and push the result back to the _Main Repo_. An empty, bare repo does not even contain a 'master' branch from the start and this can lead to some edge cases that complicate things.
 
-=== Use a git hook and shell script
+=== Scenario 1 - use a git hook and shell script
 
 First, follow the steps described in <<common_setup>>. Then proceed with the steps below.
 
@@ -125,13 +126,10 @@ git clone file:///usr/local/main_repo.git
 +
 .Find the `post-receive` template in the giblish gem
 ====
-On a server running Ubuntu 16.04, `gem which giblish` returns:
-
- /var/lib/gems/2.6.0/gems/giblish-0.7.0/lib/giblish.rb
+run the following to copy the post-receive template to your current directory:
+  
+  cp $(dirname $(gem which giblish))/../scripts/hooks/post-receive.example .
 
-and the template hook can be found under
-
- /var/lib/gems/2.6.0/gems/giblish-0.7.0/scripts/hooks/post-receive.example
 ====
 
  . Rename the copy to `post-receive`
@@ -143,8 +141,6 @@ That's it. You can now push to your _Main Repo_ and the `post-receive` hook will
 
 === Setup the git hook and Jenkins scenario
 
-TBD...
-
 First, follow the steps described in <<common_setup>>. Then proceed with the steps below.
 
 ==== Sequence for generating documents
@@ -162,7 +158,7 @@ image::Render Documents.png[]
 ====
 [source,bash]
 ----
-include::../scripts/hooks/post-receive.example[]
+include::../../scripts/hooks/post-receive.example[]
 ----
 ====
 
@@ -175,6 +171,6 @@ Below is an example of a `post-update` hook that triggers Jenkins jobs after a p
 ====
 [source,bash]
 ----
-include::../docgen/scripts/githook_examples/post-update.example[]
+include::../../scripts/hooks/post-update.example[]
 ----
 ====

data/docs/reference/develop_and_build.adoc

@@ -0,0 +1,27 @@
+= Developing and building giblish
+:docid: G-005
+
+NOTE: giblish is developed using the https://github.com/rbenv/rbenv[rbenv] ruby version manager. It is *strongly recommended* to setup and use this tool when developing or building giblish.
+
+[[build_gem]]
+== Building giblish as a gem
+
+Setup dependencies::
+ . Setup your `rbenv` environment.
+ . Check out the branch you want to build.
+ . Open a terminal in the top directory of the checked-out branch.
+ . Install giblish' dependencies using `bundle install`
+ .. *Note* The `mathematical` gem is currently a development dependency for giblish and it can be a bit tricky to build and install its native dependencies. How to do that is outside the scope of this document.
+
+ Run the unit tests::
+ . Run the unit tests using `bundle exec rake`.
+
+ Build the gem::
+ . Build the gem using `bundle exec gem build`
+
+== Publish a release
+
+ . Create a new release in GitHub using the same version nr as stated in `.../lib/version.rb`.
+ . Build the gem using the steps from <<build_gem>>.
+ . Publish the gem to https://rubygems.org/ by running `bundle exec gem push giblish-<version>.gem`
+

data/giblish.gemspec

@@ -49,7 +49,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard", "~> 1.16"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "oga", "~> 3.3"
-  # spec.add_development_dependency "thor", "~> 0.20.3"
   spec.add_development_dependency "thor", "~> 1.2"
   spec.add_development_dependency "asciidoctor-mathematical", "~> 0.3.5"
   # needed for the sinatra-based apps
@@ -61,6 +60,7 @@ Gem::Specification.new do |spec|
   # Run-time deps
   # 'matrix' needed because of incompatibilities between prawn v2.4
   # and ruby 3.1
+  # sorbet-runtime
   spec.add_runtime_dependency "matrix", "~>0.4"
   spec.add_runtime_dependency "warning", "~>1.2"
   spec.add_runtime_dependency "asciidoctor", "~>2.0", ">= 2.0.17"

data/lib/giblish/application.rb

@@ -5,54 +5,54 @@ require_relative "gitrepos/checkoutmanager"
 
 module Giblish
   # The app class for the giblish application
-  class Application
-    # returns on success, raises otherwise
-    def run(args)
-      # force immediate output
-      $stdout.sync = true
-
-      # setup logging
-      Giblog.setup
-      Giblog.logger.level = Logger::INFO
-
-      # Parse cmd line
-      cmdline = CmdLine.new.parse(args)
-      Giblog.logger.level = cmdline.log_level
-
-      Giblog.logger.debug { "cmd line args: #{cmdline.inspect}" }
-
-      # build a tree of files matching user's regexp selection
-      src_tree = PathTree.build_from_fs(cmdline.srcdir) do |p|
-        if cmdline.exclude_regex&.match(p.to_s)
-          false
-        else
-          (cmdline.include_regex =~ p.to_s)
-        end
-      end
-      if src_tree.nil?
-        Giblog.logger.warn { "Did not find any files to convert" }
-        return
-      end
-
-      app = Configurator.new(cmdline, src_tree)
-      app.tree_converter.run
-
-      Giblog.logger.info { "Giblish is done!" }
-    end
-
-    # does not return, exits with status code
-    def run_from_cmd_line
-      begin
-        run(ARGV)
-        exit_code = 0
-      rescue => exc
-        Giblog.logger.error { exc.message }
-        Giblog.logger.error { exc.backtrace }
-        exit_code = 1
-      end
-      exit(exit_code)
-    end
-  end
+  # class Application
+  #   # returns on success, raises otherwise
+  #   def run(args)
+  #     # force immediate output
+  #     $stdout.sync = true
+
+  #     # setup logging
+  #     Giblog.setup
+  #     Giblog.logger.level = Logger::INFO
+
+  #     # Parse cmd line
+  #     cmdline = CmdLine.new.parse(args)
+  #     Giblog.logger.level = cmdline.log_level
+
+  #     Giblog.logger.debug { "cmd line args: #{cmdline.inspect}" }
+
+  #     # build a tree of files matching user's regexp selection
+  #     src_tree = PathTree.build_from_fs(cmdline.srcdir) do |p|
+  #       if cmdline.exclude_regex&.match(p.to_s)
+  #         false
+  #       else
+  #         (cmdline.include_regex =~ p.to_s)
+  #       end
+  #     end
+  #     if src_tree.nil?
+  #       Giblog.logger.warn { "Did not find any files to convert" }
+  #       return
+  #     end
+
+  #     app = Configurator.new(cmdline, src_tree)
+  #     app.tree_converter.run
+
+  #     Giblog.logger.info { "Giblish is done!" }
+  #   end
+
+  #   # does not return, exits with status code
+  #   def run_from_cmd_line
+  #     begin
+  #       run(ARGV)
+  #       exit_code = 0
+  #     rescue => exc
+  #       Giblog.logger.error { exc.message }
+  #       Giblog.logger.error { exc.backtrace }
+  #       exit_code = 1
+  #     end
+  #     exit(exit_code)
+  #   end
+  # end
 
   class DirTreeConvert
     # This class provides a file as the source for the asciidoc info and
@@ -197,15 +197,20 @@ module Giblish
       Giblog.logger.level = Logger::INFO
 
       # Parse cmd line
-      user_opts = CmdLine.new.parse(args)
-      Giblog.logger.level = user_opts.log_level
-      Giblog.logger.debug { "cmd line args: #{user_opts.inspect}" }
+      @user_opts = CmdLine.new.parse(args)
+      Giblog.logger.level = @user_opts.log_level
+      Giblog.logger.debug { "cmd line args: #{@user_opts.inspect}" }
 
       # Select the coversion instance to use
-      @converter = select_conversion(user_opts)
+      @converter = select_conversion(@user_opts)
     end
 
     def run
+      begin
+        require "asciidoctor-diagram"
+      rescue LoadError
+        Giblog.logger.warn { "Did not find asciidoctor-diagram installed, diagrams will not be rendered." }
+      end
       # do the conversion
       @converter.run
     end

data/lib/giblish/treeconverter.rb

@@ -156,20 +156,20 @@ module Giblish
     }
 
     # see https://docs.asciidoctor.org/asciidoctor/latest/api/options/
-    DEFAULT_ADOC_OPTS = {
-      backend: "html5",
+    DEFAULT_ADOC_API_OPTS = {
+      # backend: "html5",
       # base_dir:
-      catalog_assets: false,
+      # catalog_assets: false,
       # converter:
-      doctype: "article",
+      # doctype: "article",
       # eruby:
       # ignore extention stuff
-      header_only: false,
+      # header_only: false,
       # logger:
-      mkdirs: false,
-      parse: true,
+      # mkdirs: false,
+      # parse: true,
       safe: :unsafe,
-      sourcemap: false,
+      # sourcemap: false,
       # template stuff TBD,
       # to_file:
       # to_dir:
@@ -192,12 +192,67 @@ module Giblish
         failure: ->(src, dst, dst_rel_path, ex, logstr) { TreeConverter.on_failure(src, dst, dst_rel_path, ex, logstr) }
       })
 
-      # merge user's options with the default, giving preference
-      # to the user
-      @adoc_api_opts = DEFAULT_ADOC_OPTS.dup
-        .merge!(opts.fetch(:adoc_api_opts, {}))
-      @adoc_api_opts[:attributes] = DEFAULT_ADOC_DOC_ATTRIBS.dup
-        .merge!(opts.fetch(:adoc_doc_attribs, {}))
+      # cache external configuration
+      @config_opts = opts.dup
+    end
+
+    # Resolve the document attributes according to the precedence.
+    #
+    # According to https://docs.asciidoctor.org/asciidoc/latest/attributes/assignment-precedence/
+    # The attribute precedence is:
+    # 1. An attribute passed to the API or CLI whose value does not end in @
+    # 2. An attribute defined in the document
+    # 3. An attribute passed to the API or CLI whose value or name ends in @
+    # 4. The default value of the attribute, if applicable
+    #
+    # giblish adds the following rules:
+    # 1.5 An attribute defined in an attribute provider for a specific source node
+    # 3.5 The default value set by giblish, if applicable
+    def resolve_doc_attributes(doc_src, node_attr)
+      # rule 3.5
+      doc_attr = DEFAULT_ADOC_DOC_ATTRIBS.dup
+
+      # sort attribs into soft and hard (rule 1 and 3)
+      soft_attr = {}
+      hard_attr = {}
+      @config_opts.fetch(:adoc_doc_attribs, {}).each do |k, v|
+        ks = k.to_s.strip
+        vs = v.to_s.strip
+
+        if ks.end_with?("@")
+          soft_attr[ks[0..]] = vs
+          next
+        end
+        if vs.end_with?("@")
+          soft_attr[ks] = vs[0..]
+          next
+        end
+        hard_attr[ks] = vs
+      end
+
+      # rule 3.
+      doc_attr.merge!(soft_attr)
+
+      # rule 2
+      Giblish.process_header_lines(doc_src.lines) do |line|
+        a = /^:(.+):(.*)$/.match(line)
+        next unless a
+        @logger.debug { "got header attr from doc: #{a[1]} : #{a[2]}" }
+        doc_attr[a[1].strip] = a[2].strip
+      end
+
+      @logger.debug { "idprefix before: #{doc_attr["idprefix"]}" }
+
+      # rule 1.5
+      doc_attr.merge!(node_attr)
+
+      # rule 1.
+      doc_attr.merge!(hard_attr)
+
+      @logger.debug { "idprefix after: #{doc_attr["idprefix"]}" }
+
+      # @logger&.debug { "Header attribs: #{doc_attr}" }
+      doc_attr
     end
 
     # require the following methods to be available from the src node:
@@ -216,34 +271,44 @@ module Giblish
       @logger&.info { "Converting #{src_node.pathname} and store result under #{dst_node.parent.pathname}" }
 
       # merge the common api opts with node specific
-      api_opts = @adoc_api_opts.dup
+      api_opts = DEFAULT_ADOC_API_OPTS.dup
+      api_opts.merge!(@config_opts.fetch(:adoc_api_opts, {}))
       api_opts.merge!(src_node.api_options(src_node, dst_node, dst_top)) if src_node.respond_to?(:api_options)
-      api_opts[:attributes].merge!(src_node.document_attributes(src_node, dst_node, dst_top)) if src_node.respond_to?(:document_attributes)
 
       # use a new logger instance for each conversion
       adoc_logger = Giblish::AsciidoctorLogger.new(@logger, @adoc_log_level)
 
       begin
-        # load the source to enable access to doc properties
+        doc_src = src_node.adoc_source(src_node, dst_node, dst_top)
+
+        node_attr = src_node.respond_to?(:document_attributes) ?
+          src_node.document_attributes(src_node, dst_node, dst_top) : {}
+        doc_attr = resolve_doc_attributes(doc_src, node_attr)
+        # piggy-back our own info on the doc attributes hash so that
+        # asciidoctor extensions can use this info later on
+        doc_attr["giblish-info"] = {
+          src_node: src_node,
+          dst_node: dst_node,
+          dst_top: dst_top
+        }
+
+        # load the source to enable access to doc attributes and properties
         #
-        # NOTE: the 'parse: false' is needed to prevent preprocessor extensions to be run as part
+        # NOTE: 'parse' is set to false to prevent preprocessor extensions to be run as part
         # of loading the document. We want them to run during the 'convert' call later when
         # doc attribs have been amended.
-        doc = Asciidoctor.load(src_node.adoc_source(src_node, dst_node, dst_top), api_opts.merge(
+        #
+        # NOTE2: by trial-and-error, it seems that some document attributes must be set when
+        # calling 'load' and not added after the call and before the 'convert' call to have
+        # the expected effect (e.g. idprefix).
+        doc = Asciidoctor.load(doc_src, api_opts.merge(
           {
+            attributes: doc_attr,
             parse: false,
             logger: adoc_logger
           }
         ))
 
-        # piggy-back our own info on the doc attributes hash so that
-        # asciidoctor extensions can use this info later on
-        doc.attributes["giblish-info"] = {
-          src_node: src_node,
-          dst_node: dst_node,
-          dst_top: dst_top
-        }
-
         # update the destination node with the correct file suffix. This is dependent
         # on the type of conversion performed
         dst_node.name = dst_node.name.sub_ext(doc.attributes["outfilesuffix"])
@@ -252,11 +317,11 @@ module Giblish
         # make sure the dst dir exists
         d.dirname.mkpath
 
-        # write the converted doc to the file
-        output = doc.convert(api_opts.merge({logger: adoc_logger}))
+        # do the conversion and write the converted doc to file
+        output = doc.convert(api_opts)
         doc.write(output, d.to_s)
 
-        # give user the opportunity to eg store the result of the conversion
+        # give the user the opportunity to eg store the result of the conversion
         # as data in the destination node
         @conv_cb[:success]&.call(src_node, dst_node, dst_top, doc, adoc_logger.in_mem_storage.string)
         true

data/lib/giblish/version.rb

@@ -1,3 +1,3 @@
 module Giblish
-  VERSION = "2.0.0-alpha1".freeze
+  VERSION = "2.0.1".freeze
 end

data/web_apps/gh_webhook_trigger/gh_webhook_trigger.rb

@@ -17,7 +17,7 @@ accesslog_path = Pathname.new(__dir__).join("log/access.log")
 accesslog_path.dirname.mkpath
 access_logger = ::Logger.new(accesslog_path.to_s)
 
-# instantiate the one-and-only web-hook-manager
+# the target directory on the server's file system
 DSTDIR = "/var/www/rillbert_se/html/public/giblish_examples/giblish"
 clone_dir = Dir.mktmpdir
 
@@ -42,32 +42,3 @@ end
 get "/" do
   ""
 end
-
-# class GenerateDocsFromGitHubHook < Sinatra::Base
-#   ::Logger.class_eval { alias_method :write, :<< }
-
-#   accesslog_path = Pathname.new(__dir__).join("../log/access.log")
-#   accesslog_path.dirname.mkpath
-#   access_logger = ::Logger.new(accesslog_path.to_s)
-
-#   errorlog_path = Pathname.new(__dir__).join("log/error.log")
-#   errorlog_path.dirname.mkpath
-#   error_logger = ::File.new(errorlog_path.to_s, "a+")
-#   error_logger.sync = true
-
-#   configure do
-#     use ::Rack::CommonLogger, access_logger
-#   end
-
-#   before {
-#     env["rack.errors"] = error_logger
-#   }
-
-#   # instantiate the one-and-only web-hook-manager
-#   wm = WebhookManager.new(/svg/, "https://github.com/rillbert/giblish.git", Dir.mktmpdir, "giblish", "docs", dstdir, error_logger)
-
-#   post "/payload" do
-#     gh_data = JSON.parse(request.body.read, symbolized_names: true)
-#     wm.run(gh_data)
-#   end
-# end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: giblish
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.alpha1
+  version: 2.0.1
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-26 00:00:00.000000000 Z
+date: 2023-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -289,17 +289,18 @@ files:
 - docs/concepts/text_search_im/cgi-search_request.svg
 - docs/concepts/text_search_im/search_request.puml
 - docs/concepts/text_search_im/search_request.svg
-- docs/howtos/trigger_generation.adoc
-- docs/howtos/trigger_generation_im/Render Documents.png
-- docs/howtos/trigger_generation_im/View Documents.png
-- docs/howtos/trigger_generation_im/deploy_with_hooks.graphml
-- docs/howtos/trigger_generation_im/deploy_with_hooks.svg
-- docs/howtos/trigger_generation_im/deploy_with_jenkins.graphml
-- docs/howtos/trigger_generation_im/deploy_with_jenkins.svg
-- docs/howtos/trigger_generation_im/docgen_github.puml
-- docs/howtos/trigger_generation_im/giblish_deployment.graphml
-- docs/howtos/trigger_generation_im/post-receive-example.sh
+- docs/howtos/setup_static_site.adoc
+- docs/howtos/setup_static_site_assets/Render Documents.png
+- docs/howtos/setup_static_site_assets/View Documents.png
+- docs/howtos/setup_static_site_assets/deploy_with_hooks.graphml
+- docs/howtos/setup_static_site_assets/deploy_with_hooks.svg
+- docs/howtos/setup_static_site_assets/deploy_with_jenkins.graphml
+- docs/howtos/setup_static_site_assets/deploy_with_jenkins.svg
+- docs/howtos/setup_static_site_assets/docgen_github.puml
+- docs/howtos/setup_static_site_assets/giblish_deployment.graphml
+- docs/howtos/setup_static_site_assets/post-receive-example.sh
 - docs/reference/box_flow_spec.adoc
+- docs/reference/develop_and_build.adoc
 - docs/reference/search_spec.adoc
 - exe/giblish
 - giblish.gemspec
@@ -378,11 +379,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: A tool for publishing asciidoc docs stored in git repos