giblish 1.0.0.rc2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 306ffd38e0b46b1da0bde8fbfe13e25edd2271cf3c9e40a0bd595e0bd92ab474
-  data.tar.gz: 63124dcd57d6bc1a4b11c8b92b4250071b4d6bb1f3068e25e8465759722c2b82
+  metadata.gz: '099246634de308661fcac8822d2bbfbee328988aa47f0722fe0aa700881aa0d3'
+  data.tar.gz: 1517b52f92efb28048ac6f8b43ddbcbde89667b5e8b351bd2ab9cee274edd636
 SHA512:
-  metadata.gz: 5f66a14a039fc925c55aef093b28db11f2aabc585b1dae43cf6ab39c42996c13ec85cfdd5f3c4decdc618caa0dfdaf8b43eb5152e9cf53c5f0e60ba50d1e9a52
-  data.tar.gz: 575c20796a4d9aef25f90760dd1fd9e1bf7897fe9284951486b214bda56cb28a835c2c6a9c8306c91c50764bfb1c3ca170756a276a45b27b94ffc59c2fe972ad
+  metadata.gz: 35275a70f4a98fefc8499325bf5dccf6351b6811cd4e73d672c3536175e72ea6421750a163d0e34aee6e8c5d553e0ce1f097fac2abd1ee5f88a81125253fbc27
+  data.tar.gz: f020e55eb9df9fc630a36904d9e6155bbfe53d0ae2c27a29610c1a114aeea249e5caa6e0e756fba82347f8884e24df0e892df507da204c3ffd6d1287d1ca6b22

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/Changelog.adoc

@@ -3,10 +3,8 @@
 == Not yet in place
 
  * Update docs for giblish.
- ** the later part of the trigger_generation doc
- ** go through and fix spelling
+ ** write detailed instructions on howto setup the doc generation examples
  * Update the default css for giblish html generation.
- * Maybe put some effort into the ConversionInfo hierarchy
 
 == v1.0.0
 

data/README.adoc

@@ -36,14 +36,12 @@ 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
 
@@ -55,12 +53,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 +74,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 +91,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.
 
@@ -175,15 +169,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 +190,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/giblish.gemspec

@@ -58,6 +58,9 @@ 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"]

data/lib/giblish/version.rb

@@ -1,3 +1,3 @@
 module Giblish
-  VERSION = "1.0.0.rc2".freeze
+  VERSION = "1.0.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: giblish
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc2
+  version: 1.0.0
 platform: ruby
 authors:
 - Anders Rillbert
@@ -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
@@ -370,9 +384,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.2.32
 signing_key: