Merge pull request chaincodelabs#69 from willcl-ark/epub

Author: willcl-ark

.gitignore

@@ -6,3 +6,4 @@ _site
 .jekyll-cache
 .jekyll-metadata
 vendor
+images

Gemfile

@@ -5,6 +5,9 @@ source 'https://rubygems.org'
 ## version.
 ruby '3.2.2'
 
+gem "asciidoctor", "~>2.0.20"
+gem "rouge"
+
 ## If you add a new Gem below, run `bundle install` to install it.
 group :development do
   gem "jekyll", "~> 4.3.2"
@@ -16,11 +19,14 @@ group :development do
 end
 
 group :jekyll_plugins do
+  gem "asciidoctor-diagram"
   gem "jekyll-feed", "~> 0.12"
   gem "jekyll-asciidoc", "~> 3.0.0"
-  gem "asciidoctor-diagram"
+end
+
+group :asciidoc_plugins do
+  gem "asciidoctor-epub3"
   gem "asciidoctor-pdf"
-  gem 'rouge'
 end
 
 group :testing do

Gemfile.lock

@@ -6,13 +6,17 @@ GEM
       public_suffix (>= 2.0.2, < 6.0)
     afm (0.2.2)
     asciidoctor (2.0.20)
-    asciidoctor-diagram (2.2.11)
+    asciidoctor-diagram (2.2.14)
       asciidoctor (>= 1.5.7, < 3.x)
       asciidoctor-diagram-ditaamini (~> 1.0)
       asciidoctor-diagram-plantuml (~> 1.2021)
       rexml
     asciidoctor-diagram-ditaamini (1.0.3)
-    asciidoctor-diagram-plantuml (1.2023.10)
+    asciidoctor-diagram-plantuml (1.2023.12)
+    asciidoctor-epub3 (1.5.1)
+      asciidoctor (>= 1.5.6, < 3.0.0)
+      gepub (~> 1.0.0)
+      mime-types (~> 3.0)
     asciidoctor-pdf (2.3.9)
       asciidoctor (~> 2.0)
       concurrent-ruby (~> 1.1)
@@ -23,12 +27,12 @@ GEM
       prawn-table (~> 0.2.0)
       prawn-templates (~> 0.1.0)
       treetop (~> 1.6.0)
-    async (2.6.3)
+    async (2.6.5)
       console (~> 1.10)
       fiber-annotation
       io-event (~> 1.1)
       timers (~> 4.1)
-    chef-utils (18.2.7)
+    chef-utils (18.3.0)
       concurrent-ruby
     colorator (1.1.0)
     concurrent-ruby (1.2.2)
@@ -43,11 +47,14 @@ GEM
     ethon (0.16.0)
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
-    ffi (1.15.5)
+    ffi (1.16.3)
     fiber-annotation (0.2.0)
     fiber-local (1.0.0)
     forwardable-extended (2.6.0)
-    google-protobuf (3.24.0-x86_64-linux)
+    gepub (1.0.15)
+      nokogiri (>= 1.8.2, < 2.0)
+      rubyzip (> 1.1.1, < 2.4)
+    google-protobuf (3.25.1-x86_64-linux)
     hashery (2.1.2)
     html-proofer (5.0.8)
       addressable (~> 2.3)
@@ -61,7 +68,7 @@ GEM
     http_parser.rb (0.8.0)
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
-    io-event (1.2.3)
+    io-event (1.3.3)
     jekyll (4.3.2)
       addressable (~> 2.4)
       colorator (~> 1.0)
@@ -78,11 +85,13 @@ GEM
       safe_yaml (~> 1.0)
       terminal-table (>= 1.8, < 4.0)
       webrick (~> 1.7)
-    jekyll-asciidoc (3.0.0)
-      asciidoctor (>= 1.5.0)
+    jekyll-asciidoc (3.0.1)
+      asciidoctor (>= 1.5.0, < 3.0.0)
       jekyll (>= 3.0.0)
     jekyll-feed (0.17.0)
       jekyll (>= 3.7, < 5.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
     jekyll-redirect-from (0.16.0)
       jekyll (>= 3.3, < 5.0)
     jekyll-sass-converter (3.0.0)
@@ -91,10 +100,11 @@ GEM
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    json-schema (4.0.0)
+    json-schema (4.1.1)
       addressable (>= 2.8)
-    just-the-docs (0.5.4)
+    just-the-docs (0.7.0)
       jekyll (>= 3.8.5)
+      jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
       rake (>= 12.3.1)
     kramdown (2.4.0)
@@ -106,19 +116,22 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     matrix (0.4.2)
-    mdl (0.12.0)
+    mdl (0.13.0)
       kramdown (~> 2.3)
       kramdown-parser-gfm (~> 1.1)
       mixlib-cli (~> 2.1, >= 2.1.1)
       mixlib-config (>= 2.2.1, < 4)
       mixlib-shellout
     mercenary (0.4.0)
+    mime-types (3.5.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2023.1003)
     mixlib-cli (2.1.8)
     mixlib-config (3.0.27)
       tomlrb
     mixlib-shellout (3.2.7)
       chef-utils
-    nokogiri (1.15.4-x86_64-linux)
+    nokogiri (1.15.5-x86_64-linux)
       racc (~> 1.4)
     parslet (2.0.0)
     pathutil (0.16.2)
@@ -145,18 +158,19 @@ GEM
     prawn-templates (0.1.2)
       pdf-reader (~> 2.0)
       prawn (~> 2.2)
-    public_suffix (5.0.3)
-    racc (1.7.1)
+    public_suffix (5.0.4)
+    racc (1.7.3)
     rainbow (3.1.1)
-    rake (13.0.6)
+    rake (13.1.0)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     rexml (3.2.6)
-    rouge (4.1.3)
+    rouge (4.2.0)
     ruby-rc4 (0.1.5)
+    rubyzip (2.3.2)
     safe_yaml (1.0.5)
-    sass-embedded (1.64.2-x86_64-linux-gnu)
+    sass-embedded (1.69.5-x86_64-linux-gnu)
       google-protobuf (~> 3.23)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
@@ -167,18 +181,20 @@ GEM
     treetop (1.6.12)
       polyglot (~> 0.3)
     ttfunk (1.7.0)
-    typhoeus (1.4.0)
+    typhoeus (1.4.1)
       ethon (>= 0.9.0)
-    unicode-display_width (2.4.2)
+    unicode-display_width (2.5.0)
     webrick (1.8.1)
     yell (2.2.2)
-    zeitwerk (2.6.11)
+    zeitwerk (2.6.12)
 
 PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  asciidoctor (~> 2.0.20)
   asciidoctor-diagram
+  asciidoctor-epub3
   asciidoctor-pdf
   html-proofer
   jekyll (~> 4.3.2)

Makefile

@@ -1,4 +1,5 @@
 all: test-before-build build-other-versions build test-after-build
+build-other-versions: html pdf epub
 publish: test-before-build build-other-versions build
 production: clean all production-test
 
@@ -45,14 +46,20 @@ test-after-build: build
 	## Check for broken links
 	bundle exec htmlproofer --disable-external --ignore-urls '/^\/bin/.*/' ./_site
 
-build-other-versions:
+html:
 	mkdir -p bin
 	## Single page HTML
 	## Set imagesdir to parent_dir/images to work with jekyll build
-	bundle exec asciidoctor -r asciidoctor-diagram -o onboarding-to-bitcoin-core.html index.adoc --attribute imagesdir=../images
+	bundle exec asciidoctor -r asciidoctor-diagram -o onboarding-to-bitcoin-core.html index.adoc
 	## Delete non-deterministic asciidoctor output
 	sed -i '/^Last updated /d' onboarding-to-bitcoin-core.html
 	mv onboarding-to-bitcoin-core.html bin/
-	## PDF version
-	bundle exec asciidoctor -r asciidoctor-pdf -b pdf -r asciidoctor-diagram -o onboarding-to-bitcoin-core.pdf index.adoc --attribute imagesdir=../images
+	cp -r images bin/
+
+pdf:
+	bundle exec asciidoctor -r asciidoctor-pdf -b pdf -r asciidoctor-diagram -o onboarding-to-bitcoin-core.pdf index_pdf.adoc
 	mv onboarding-to-bitcoin-core.pdf bin/
+
+epub:
+	asciidoctor -b epub3 -r asciidoctor-epub3 -r asciidoctor-diagram -o index.epub index_epub.adoc
+	mv index.epub bin/onboarding-to-bitcoin-core.epub

_config.yml

@@ -21,7 +21,7 @@
 title: Bitcoin Core Onboarding
 email: [email protected]
 description: >- # this means to ignore newlines until "baseurl:"
-  Bitcoin Core developer obboarding documentation
+  Bitcoin Core developer onboarding documentation
 baseurl: "" # the subpath of your site, e.g. /blog
 url: "https://bitcoincore.academy" # the base hostname & protocol for your site, e.g. http://example.com
 twitter_username: chaincodelabs
@@ -30,14 +30,19 @@ github_username:  chaincodelabs
 # Build settings
 theme: just-the-docs
 plugins:
+  - asciidoctor-diagram
   - jekyll-feed
+  - jekyll-asciidoc
 
 asciidoc:
   processor: asciidoctor
 
 asciidoctor:
   attributes:
-    imagesdir: images
+    imagesdir: /images
+    mermaid-config: mermaid-config.json
+    mermaid-format: svg
+    mermaid-puppeteer-config: puppeteer-config.json
     source-highlighter: rouge
     rouge-style: github
     icons: font
@@ -67,6 +72,7 @@ mermaid:
 # their entries' file path in the `include:` list.
 exclude:
   - .jekyll-cache/
+  - all_chapters.adoc
   - 01_overview-and-development.adoc
   - 02_architecture.adoc
   - 03_consensus-and-validation.adoc
@@ -79,7 +85,8 @@ exclude:
   - 10_rpc.adoc
   - asciidoc_workflow.adoc
   - index.adoc
-  - old.index.adoc
+  - index_pdf.adoc
+  - index_epub.adoc
   - settings.adoc
   - README.adoc
   - book.html

addition-removal-mempool.adoc

@@ -46,7 +46,7 @@ Transactions are removed from the mempool for a number of reasons:
 . The mempool must be trimmed back down below its maximum size `TrimToSize()`
 
 .Removal from the mempool
-[mermaid,target=mempool-removal,format=svg,align="center"]
+[mermaid,target=mempool-removal,align="center"]
 ....
 flowchart LR
     remove_staged["RemoveStaged()"]

all_chapters.adoc

@@ -0,0 +1,23 @@
+include::01_overview-and-development.adoc[]
+
+include::02_architecture.adoc[]
+
+include::03_consensus-and-validation.adoc[]
+
+include::04_wallet.adoc[]
+
+include::05_gui.adoc[]
+
+include::06_p2p.adoc[]
+
+include::07_mempool.adoc[]
+
+include::08_script.adoc[]
+
+include::09_build-system.adoc[]
+
+include::10_rpc.adoc[]
+
+include::appendix.adoc[]
+
+include::glossary.adoc[]

components-overview.adoc

@@ -11,7 +11,7 @@ WARNING: This diagram is **not** exhaustive and includes simplifications.
 NOTE: dashed lines indicate optional components
 
 .`bitcoind` overview
-[mermaid, target=bitcoind-overview, format=svg, id=bitcoind-overview]
+[mermaid, target=bitcoind-overview, id=bitcoind-overview]
 ....
 flowchart LR
     bitcoind
@@ -77,7 +77,7 @@ The following diagram gives a brief overview of the major components in bitcoin-
 WARNING: This diagram is **not** exhaustive and includes simplifications.
 
 .`bitcoin-cli` overview
-[mermaid, target=bitcoin-cli-overview, format=svg, id=bitcoin-cli-overview-chart]
+[mermaid, target=bitcoin-cli-overview, id=bitcoin-cli-overview-chart]
 ....
 flowchart LR
     BaseRequestHandler["BaseRequestHandler()"]
@@ -105,7 +105,7 @@ WARNING: This diagram is **not** exhaustive and includes simplifications.
 NOTE: dashed lines indicate optional components
 
 .Wallet structure overview
-[mermaid, target=bitcoin-wallet-overview, format=svg]
+[mermaid, target=bitcoin-wallet-overview]
 ....
 flowchart LR
     ScriptPubKeyMan --> DescriptorScriptPubKeyMan

consensus-and-validation.adoc

@@ -1,7 +1,7 @@
-= Consensus and Validation
 :page-nav_order: 20
 :page-has_children: true
 include::links-onepage.adoc[]
+= Consensus and Validation
 
 TIP: This section has been updated to Bitcoin Core @ https://github.com/bitcoin/bitcoin/tree/v23.0[v23.0^]