giblish 2.0.0.pre.alpha1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc5f7111b85423074f87986b2750ce3fa61dbf4364331a80481d0d5cc881673
-  data.tar.gz: 53fd77b1ac62eec70539e744950cfc8f121532f9639eb2bcb860d6142443474f
+  metadata.gz: 536fb7fa58df4bca2bfa5b73f68ebec0dd32bff797c3401cd20e6ccb20450db7
+  data.tar.gz: 3f6f51691b25f64cf80da13d9467f5ea8f1ee296390efd7f77cd0ce49d7195c7
 SHA512:
-  metadata.gz: baa8d72424dc2cb581e90bf383849cb8043b13ca1aed2c5fe3a4b1d9a20aedccf69f6ac9936e7439ae1887074bf274a47553907bce1ce78decd68da207ca3b91
-  data.tar.gz: b579918b4aa8c68d0f9e1ac57a878e3279b3c8404e6f5e677e91859a6af45983feaca033bf051eff56ac7e4f45556f13faa5b79a7bbcb7fc47f18684b5fa952f
+  metadata.gz: 855851b721c005724dd76daeafeb43945bda104f0edc3628530efa4b1a87bece735547be67f9ac584fbae8b1b640f36b19cc98112864e22ff1edd775be23a9a6
+  data.tar.gz: ef6c403e03b3abf628ddd896e935f3dbaf096a4368bb1702d665f269de1eddbccd2a2efeb2647e00dfa18888a7b82d47be711b39e4cddedcd7006ede4d96d471

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

data/Changelog.adoc

@@ -1,11 +1,21 @@
 = 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.
- ** 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.
 
+== 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.

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/lib/giblish/version.rb

@@ -1,3 +1,3 @@
 module Giblish
-  VERSION = "2.0.0-alpha1".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: 2.0.0.pre.alpha1
+  version: 2.0.0
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-26 00:00:00.000000000 Z
+date: 2022-08-29 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,9 +379,9 @@ 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
 signing_key: