giblish 1.0.0.rc2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 306ffd38e0b46b1da0bde8fbfe13e25edd2271cf3c9e40a0bd595e0bd92ab474
-  data.tar.gz: 63124dcd57d6bc1a4b11c8b92b4250071b4d6bb1f3068e25e8465759722c2b82
+  metadata.gz: 536fb7fa58df4bca2bfa5b73f68ebec0dd32bff797c3401cd20e6ccb20450db7
+  data.tar.gz: 3f6f51691b25f64cf80da13d9467f5ea8f1ee296390efd7f77cd0ce49d7195c7
 SHA512:
-  metadata.gz: 5f66a14a039fc925c55aef093b28db11f2aabc585b1dae43cf6ab39c42996c13ec85cfdd5f3c4decdc618caa0dfdaf8b43eb5152e9cf53c5f0e60ba50d1e9a52
-  data.tar.gz: 575c20796a4d9aef25f90760dd1fd9e1bf7897fe9284951486b214bda56cb28a835c2c6a9c8306c91c50764bfb1c3ca170756a276a45b27b94ffc59c2fe972ad
+  metadata.gz: 855851b721c005724dd76daeafeb43945bda104f0edc3628530efa4b1a87bece735547be67f9ac584fbae8b1b640f36b19cc98112864e22ff1edd775be23a9a6
+  data.tar.gz: ef6c403e03b3abf628ddd896e935f3dbaf096a4368bb1702d665f269de1eddbccd2a2efeb2647e00dfa18888a7b82d47be711b39e4cddedcd7006ede4d96d471

data/.github/workflows/unit_tests.yml

@@ -2,14 +2,14 @@ name: Giblish CI checks
 
 on:
   push:
-    branches: [personal/rillbert/svg_index]
+    branches: [personal/rillbert/*, main]
 
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ["2.7", "3.0"]
+        ruby-version: ["2.7", "3.0", "3.1"]
 
     steps:
       - name: Install binutils

data/.ruby-version

@@ -1 +1 @@
-3.0.3
+3.1.2

data/Changelog.adoc

@@ -1,12 +1,20 @@
 = giblish changelog
+:docid: G-006
 
 == Not yet in place
 
+ * Investigate how to remove tmp/cache files and dirs during graph generation
  * Update docs for giblish.
- ** the later part of the trigger_generation doc
- ** go through and fix spelling
+ ** write instructions for github webhook triggered generation
  * Update the default css for giblish html generation.
- * Maybe put some effort into the ConversionInfo hierarchy
+
+== 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
 

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.
 
 |===
 
@@ -36,18 +36,18 @@ IMPORTANT: The examples below are *not* the official documentation for the corre
 The features of giblish include:
 
  * An index page listing all rendered documents with clickable links.
- * A (stripped-down but nonetheless useful) text-search of your (html) documents (requires that you view your docs via a web-server.
  * If the source directory tree is part of a git repository, giblish can generate separate html/pdf trees for branches and/or tags that match a user specified regexp (see examples below).
  * Document ids - Note: the implementation of this is giblish-specific and thus you need to render your adoc files using giblish to make this work as intended. You can use document ids to:
  ** Reference one doc in the source tree from another doc without depending on file names or relative paths. The referenced doc can thus be moved within the source tree or change its file name and the reference will still be valid.
  ** Validate doc id references during document rendering and thus be alerted to any invalid doc id references.
  ** Let giblish generate a clickable graph of all document references (requires graphviz and the 'dot' tool).
-
-NOTE: giblish shall be considered stable from a usage perspective, please report bugs to the issue tracker. It's API however, is to be considered alpha, meaning that future versions may break the current usage of cmd line flags, generated artifacts, styling or other functionality.
+ * A stripped-down, but nonetheless useful, text-search of your html documents. This requires that you publish your docs to a web-server and setup an application on that same web-server. `giblish` provides most of the scaffolding though.
 
 == 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
 
@@ -55,12 +55,6 @@ Giblish uses the awesome *asciidoctor* and *asciidoctor-pdf* projects under the
 
 Want to get started straight away? Go directly to the <<usage_examples>>.
 
-// install script for linux deps to the mathematica gem:
-// https://github.com/gjtorikian/mathematical/blob/47041d5492cc7c5f04105031430fb44119406f49/script/install_linux_deps
-//
-// Graphviz needed for some tests to pass
-
-
 === Some caveats
 
 When using giblish for generating docs the following applies:
@@ -82,6 +76,8 @@ Pull requests must meet the following to be considered for merging:
 To develop on giblish, you:
 
  . Install ruby on your local machine (rbenv is a good choice for handling ruby installations)
+ . Install necessary dependencies to install the ruby 'mathematica' gem, see eg https://github.com/gjtorikian/mathematical/blob/47041d5492cc7c5f04105031430fb44119406f49/script/install_linux_deps
+ . Install graphviz
  . Clone or fork the repository
  . Run the `bin/setup` script from a bash prompt
 
@@ -97,8 +93,8 @@ giblish extends the cross reference concept in asciidoc with a _document id_ mec
 
 Using doc ids makes it possible for giblish to do two things:
 
- . Make the reference from one document to another work even if one of the documents have been moved within the source tree.
- . Produce a clickable 'map' of the generated documents where the different references are clearly seen (this feature require that the 'dot' tool, part of the graphwiz package is installed on the machine where giblish is run).
+ . Make references from one document in the tree to another work even if one of the documents have been moved within the document source tree.
+ . Produce a clickable 'map' of the generated documents where the different references are clearly seen. This feature require that the 'dot' tool, part of the graphwiz package is installed on the machine where giblish is run.
 
 The use of the -d switch makes giblish parse the document twice, once to map up the doc ids and all references to them, once to actually generate the output documentation. Thus, you pay a performance penalty but this should not be a big inconvenience since the generation is quite fast in itself.
 
@@ -113,7 +109,7 @@ Example document one::
 = Document one
 :toc:
 :numbered:
-:docid: G-001
+:docid: AB-001
 
 == Purpose
 
@@ -126,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.
@@ -175,15 +171,15 @@ Generate html that can be browsed locally from file:://<my_dst_root>.
 
  * convert all .adoc or .ADOC files under the dir `my_src_root` to html and place the resulting files under the `my_dst_root` dir.
  * generate an index page named `index.html` that contains links and some info about the converted files. The file is placed in the `my_dst_root` dir.
- * copy the `css`, `fonts` and `images` directories found under `<working_dir>/path/to/my/resources` to `my_dst_root/web_assets`
- * link all generated html files to the css found at `/web_assets/css/mylayout.css`
+ * copy everything found under `<working_dir>/path/to/my/resources` to `my_dst_root/web_assets`
+ * link all generated html files to the mylayout.css found somewhere under `/web_assets`
 
 === Using a custom pdf theme for the generated pdfs
 
  giblish -f pdf -r path/to/my/resources -s mylayout my_src_root my_dst_root
 
  * convert all .adoc or .ADOC files under the dir `my_src_root` to pdf and place the resulting files under the `my_dst_root` dir. some info about the converted files. The file is placed in the `my_dst_root` dir.
- * the generated pdf will use the theme found at `<working_dir>/path/to/my/resources/themes/mylayout.yml`
+ * the pdfs will be rendered using the theme file named mylayout.yml found somewhere under `<working_dir>/path/to/my/resources`
 
 === Generate html from multiple git branches
 
@@ -196,72 +192,72 @@ Generate html that can be browsed locally from file:://<my_dst_root>.
  ** generate an index page named `index.html` that contains links and some info about the converted files. The file is placed in the `my_dst_root/<branch_name` dir.
  * generate a summary page containing links to a all branches and place it in the `my_dst_root` dir.
 
-=== Publish the asciidoctor.org documents with text search
+// === Publish the asciidoctor.org documents with text search
 
-giblish can be used to generate html docs suitable for serving via a web server (e.g. Apache). You can use the cgi script included in the giblish gem to provide text search capabilities.
+// giblish can be used to generate html docs suitable for serving via a web server (e.g. Apache). You can use the cgi script included in the giblish gem to provide text search capabilities.
 
-Here is an example of how to publish the docs in the official asciidoctor.org git repo to a web server, including index pages and text search.
+// Here is an example of how to publish the docs in the official asciidoctor.org git repo to a web server, including index pages and text search.
 
-NOTE: No consideration has been taken to how permissions are set up on the web server. Just running the below commands as-is on e.g.a standard apache set-up will bail out with 'permission denied' errors.
+// NOTE: No consideration has been taken to how permissions are set up on the web server. Just running the below commands as-is on e.g.a standard apache set-up will bail out with 'permission denied' errors.
 
-==== Generating the html documents
+// ==== Generating the html documents
 
-The example assumes that you have one machine where you generate the documents and another machine that runs a web server to which you have ssh access.
+// The example assumes that you have one machine where you generate the documents and another machine that runs a web server to which you have ssh access.
 
-The generated docs shall be accessible via _www.example.com/adocorg/with_search_
+// The generated docs shall be accessible via _www.example.com/adocorg/with_search_
 
-You need to provide two pieces of deployment info to giblish when generating the documents:
+// You need to provide two pieces of deployment info to giblish when generating the documents:
 
- * the uri path where to access the deployed docs (/adocorg/with_search in this example)
- * the path in the local file system on the web server where the search data can be accessed
-   (/var/www/html/site_1/adocorg/with_search in this example)
+//  * the uri path where to access the deployed docs (/adocorg/with_search in this example)
+//  * the path in the local file system on the web server where the search data can be accessed
+//    (/var/www/html/site_1/adocorg/with_search in this example)
 
-The following commands will generate the asciidoctor.org documentation and deploy the result to the web server.
+// The following commands will generate the asciidoctor.org documentation and deploy the result to the web server.
 
- . Clone the asciidoctor doc repo to your development machine
-+
- git clone https://github.com/asciidoctor/asciidoctor.org.git
+//  . Clone the asciidoctor doc repo to your development machine
+// +
+//  git clone https://github.com/asciidoctor/asciidoctor.org.git
 
- . Generate the html documentation with the correct deployment info
-+
- giblish -j '^.*_include.*' -m -mp /var/www/html/site_1/adocorg/with_search -w /adocorg/with_search -g master --index-basename "myindex" asciidoctor.org/docs ./generated_docs
-+
-Explanation of the parameters and arguments::
- * *pass:[-j '^.*_include.*']* - exclude everything in the __include_ directory. (the
-                                 asciidoctor.org repo stores partial docs here).
- * *-m* - assemble the necessary search data to support text search and include this data as part of
-          the generated documents.
- * *-mp /var/www/html/site_1/adocorg/with_search* - the file system path on the deployment machine where
-                                                    the search data is located
- * *-w /adocorg/with_search* - the uri path to the deployed docs
- * *-g master* - publish all git branches that matches the regexp 'master' (i.e. only the 'master'
-                 branch).
- * *--index-basename "myindex"* - change the default name (index) that giblish uses for the generated
-                                  index page. This is needed since asciidoctor.org contains an
-                                  "index.adoc" file that would otherwise be overwritten by giblish.
- * *asciidoctor.org/docs* - the root of the source document tree.
- * *./generated_docs* - a temporary storage for the generated html docs on the local system.
-+
+//  . Generate the html documentation with the correct deployment info
+// +
+//  giblish -j '^.*_include.*' -m -mp /var/www/html/site_1/adocorg/with_search -w /adocorg/with_search -g master --index-basename "myindex" asciidoctor.org/docs ./generated_docs
+// +
+// Explanation of the parameters and arguments::
+//  * *pass:[-j '^.*_include.*']* - exclude everything in the __include_ directory. (the
+//                                  asciidoctor.org repo stores partial docs here).
+//  * *-m* - assemble the necessary search data to support text search and include this data as part of
+//           the generated documents.
+//  * *-mp /var/www/html/site_1/adocorg/with_search* - the file system path on the deployment machine where
+//                                                     the search data is located
+//  * *-w /adocorg/with_search* - the uri path to the deployed docs
+//  * *-g master* - publish all git branches that matches the regexp 'master' (i.e. only the 'master'
+//                  branch).
+//  * *--index-basename "myindex"* - change the default name (index) that giblish uses for the generated
+//                                   index page. This is needed since asciidoctor.org contains an
+//                                   "index.adoc" file that would otherwise be overwritten by giblish.
+//  * *asciidoctor.org/docs* - the root of the source document tree.
+//  * *./generated_docs* - a temporary storage for the generated html docs on the local system.
+// +
 
- . Copy the generated files to the web server
+//  . Copy the generated files to the web server
 
- scp -r ./generated_docs rillbert@my.web.server.org:/var/www/adocorg/with_search/.
-+
+//  scp -r ./generated_docs rillbert@my.web.server.org:/var/www/adocorg/with_search/.
+// +
 
 
-==== Copy the text search script to the web server
+// ==== Copy the text search script to the web server
 
-This only needs to be done once (or if a new version of giblish breaks the currently used API).
+// This only needs to be done once (or if a new version of giblish breaks the currently used API).
 
-IMPORTANT: The current version of giblish expects the script to be found at the URI path `/cgi-bin/giblish-search.cgi`. This might be customizable in future versions but is currently hard-coded. Thus, if your web-server serves pages at www.mywebsite.com, the search script must be accessible at www.mywebsite.com/cgi-bin/giblish-search.cgi
+// IMPORTANT: The current version of giblish expects the script to be found at the URI path `/cgi-bin/giblish-search.cgi`. This might be customizable in future versions but is currently hard-coded. Thus, if your web-server serves pages at www.mywebsite.com, the search script must be accessible at www.mywebsite.com/cgi-bin/giblish-search.cgi
 
- . Find the server side script that implements text search that is included with giblish
+//  . Find the server side script that implements text search that is included with giblish
 
- gem which giblish
-+
+//  gem which giblish
+// +
 
-In my case this returns `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish.rb`. This means that I will find the script in the same directory, i.e. `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib`.
+// In my case this returns `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish.rb`. This means that I will find the script in the same directory, i.e. `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib`.
 
- . Copy the server side script to the /cgi-bin dir on the web server. In this example the cgi-bin dir is configured to be `/var/www/cgi-bin`
-+
- scp /var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish-search.cgi rillbert@my.web.server.org:/var/www/cgi-bin/giblish-search.cgi
+//  . Copy the server side script to the /cgi-bin dir on the web server. In this example the cgi-bin dir is configured to be `/var/www/cgi-bin`
+// +
+//  scp /var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish-search.cgi rillbert@my.web.server.org:/var/www/cgi-bin/giblish-search.cgi

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

@@ -45,11 +45,12 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Development deps
-  spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "standard", "~> 1.1"
+  spec.add_development_dependency "minitest", "~> 5.16"
+  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", "~> 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
   spec.add_development_dependency "sinatra", "~>2.1"
@@ -58,11 +59,14 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rack-test", "1.1"
 
   # Run-time deps
+  # 'matrix' needed because of incompatibilities between prawn v2.4
+  # and ruby 3.1
+  spec.add_runtime_dependency "matrix", "~>0.4"
   spec.add_runtime_dependency "warning", "~>1.2"
   spec.add_runtime_dependency "asciidoctor", "~>2.0", ">= 2.0.17"
   spec.add_runtime_dependency "asciidoctor-diagram", ["~> 2.2"]
-  spec.add_runtime_dependency "asciidoctor-pdf", ["~> 1.6", ">= 1.6.2"]
-  spec.add_runtime_dependency "git", "~> 1.9"
-  spec.add_runtime_dependency "rouge", "~> 3.0"
+  spec.add_runtime_dependency "asciidoctor-pdf", ["~> 2.3"]
+  spec.add_runtime_dependency "git", "~> 1.12"
+  spec.add_runtime_dependency "rouge", "~> 3.30"
   spec.add_runtime_dependency "prawn-svg", "~> 0.32.0"
 end

data/lib/giblish/application.rb

@@ -232,10 +232,10 @@ module Giblish
 
     def select_conversion(user_opts)
       case user_opts
-        in {branch_regex: _} | {tag_regex: _}
-          GitRepoConvert.new(user_opts)
-        else
-          DirTreeConvert.new(user_opts)
+      in {branch_regex: _} | {tag_regex: _}
+        GitRepoConvert.new(user_opts)
+      else
+        DirTreeConvert.new(user_opts)
       end
     end
   end

data/lib/giblish/cmdline.rb

@@ -285,12 +285,12 @@ module Giblish
       end
 
       if opts.make_searchable && opts.format != "html"
-        raise OptionParser::InvalidArgument, "Error: The --make-searchable option "\
+        raise OptionParser::InvalidArgument, "Error: The --make-searchable option " \
         "is only supported for html rendering."
       end
 
       if opts.search_action_path && !opts.make_searchable
-        raise OptionParser::InvalidArgument, "Error: The --server-search-path "\
+        raise OptionParser::InvalidArgument, "Error: The --server-search-path " \
         "flag is only supported in combination with the --make-searchable (-m) flag."
       end
     end

data/lib/giblish/configurator.rb

@@ -86,10 +86,10 @@ module Giblish
       )
 
       layout_config = case config_opts
-        in format: "html" then HtmlLayoutConfig.new(config_opts)
-        in format: "pdf" then PdfLayoutConfig.new(config_opts)
-        else
-          raise OptionParser::InvalidArgument, "The given cmd line flags are not supported: #{config_opts.inspect}"
+      in format: "html" then HtmlLayoutConfig.new(config_opts)
+      in format: "pdf" then PdfLayoutConfig.new(config_opts)
+      else
+        raise OptionParser::InvalidArgument, "The given cmd line flags are not supported: #{config_opts.inspect}"
       end
 
       # setup all options from the chosen layout configuration but

data/lib/giblish/docattr_providers.rb

@@ -43,7 +43,7 @@ module Giblish
     # pdf_font_dirs:: one or more Pathnames to each font dir that shall be
     # checked for fonts
     def initialize(pdf_style_path, *pdf_font_dirs)
-      @pdf_style_path = pdf_style_path
+      @pdf_theme_path = pdf_style_path
       # one can specify multiple font dirs as:
       # -a pdf-fontsdir="path/to/fonts;path/to/more-fonts"
       # Always use the GEM_FONTS_DIR token to load the adoc-pdf gem's font dirs as well
@@ -52,8 +52,8 @@ module Giblish
 
     def document_attributes(src_node, dst_node, dst_top)
       result = {
-        "pdf-style" => @pdf_style_path.basename.to_s,
-        "pdf-stylesdir" => @pdf_style_path.dirname.to_s,
+        "pdf-theme" => @pdf_theme_path.basename.to_s,
+        "pdf-themesdir" => @pdf_theme_path.dirname.to_s,
         "icons" => "font"
       }
       result["pdf-fontsdir"] = @pdf_fontsdir unless @pdf_fontsdir.nil?

data/lib/giblish/indexbuilders/dotdigraphadoc.rb

@@ -115,10 +115,10 @@ module Giblish
       # out-of-the-box for pdf).
       rp = conv_info.dst_rel_path
       dot_entry += case rp.extname
-                   when ".html"
-                     ", URL=\"#{rp}\" ]"
-                   else
-                     " ]"
+      when ".html"
+        ", URL=\"#{rp}\" ]"
+      else
+        " ]"
       end
       doc_dict[doc_id] = dot_entry
     end

data/lib/giblish/search/headingindexer.rb

@@ -181,7 +181,7 @@ module Giblish
             # we did not get a heading, this is ok as well but we can not
             # index it
             Giblog.logger.debug do
-              "Did not index the anchor: #{match_str} at "\
+              "Did not index the anchor: #{match_str} at " \
               "line #{line_no}, probably not associated with a heading."
             end
           end

data/lib/giblish/search/searchquery.rb

@@ -7,12 +7,12 @@ module Giblish
 
     def initialize(uri: nil, query_params: nil)
       @parameters = case [uri, query_params]
-        in [String, nil]
-          uri_2_params(uri)
-        in [nil, _]
-          validate_parameters(query_params)
-        else
-          raise ArgumentError, "You must supply one of 'uri: [String]' or 'query_params: [Hash]' got: #{query_params}"
+      in [String, nil]
+        uri_2_params(uri)
+      in [nil, _]
+        validate_parameters(query_params)
+      else
+        raise ArgumentError, "You must supply one of 'uri: [String]' or 'query_params: [Hash]' got: #{query_params}"
       end
     end
 

data/lib/giblish/version.rb

@@ -1,3 +1,3 @@
 module Giblish
-  VERSION = "1.0.0.rc2".freeze
+  VERSION = "2.0.0".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: 1.0.0.rc2
+  version: 2.0.0
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-30 00:00:00.000000000 Z
+date: 2022-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.16'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.16'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.20.3
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.20.3
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: asciidoctor-mathematical
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +150,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: matrix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: warning
   requirement: !ruby/object:Gem::Requirement
@@ -204,48 +218,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.6.2
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.6.2
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: git
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.12'
 - !ruby/object:Gem::Dependency
   name: rouge
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.30'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.30'
 - !ruby/object:Gem::Dependency
   name: prawn-svg
   requirement: !ruby/object:Gem::Requirement
@@ -281,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
@@ -370,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.2.32
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: A tool for publishing asciidoc docs stored in git repos