split header

Author: cirosantilli

Gemfile

@@ -1,5 +1,6 @@
 source 'https://rubygems.org'
 
-gem 'asciidoctor', '2.0.10'
+gem 'asciidoctor', '2.0.11'
+gem 'asciidoctor-multipage', '0.0.12'
 #gem 'jekyll', '3.8.6'
 gem 'github-pages'

Gemfile.lock

@@ -8,7 +8,9 @@ GEM
       tzinfo (~> 1.1)
     addressable (2.6.0)
       public_suffix (>= 2.0.2, < 4.0)
-    asciidoctor (2.0.10)
+    asciidoctor (2.0.11)
+    asciidoctor-multipage (0.0.12)
+      asciidoctor (>= 2.0.11, < 2.1)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
@@ -243,8 +245,9 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  asciidoctor (= 2.0.10)
+  asciidoctor (= 2.0.11)
+  asciidoctor-multipage (= 0.0.12)
   github-pages
 
 BUNDLED WITH
-   2.0.2
+   2.2.5

README.adoc

@@ -18,7 +18,11 @@ https://zenodo.org/badge/latestdoi/64534859[image:https://zenodo.org/badge/64534
 
 TL;DR: xref:qemu-buildroot-setup-getting-started[xrefstyle=full]
 
-The source code for this page is located at: https://github.com/cirosantilli/linux-kernel-module-cheat[]. Due to https://github.com/isaacs/github/issues/1610[a GitHub limitation], this README is too long and not fully rendered on github.com, so either use: https://cirosantilli.com/linux-kernel-module-cheat or <<build-the-documentation,build the docs yourself>>.
+The source code for this page is located at: https://github.com/cirosantilli/linux-kernel-module-cheat[]. Due to https://github.com/isaacs/github/issues/1610[a GitHub limitation], this README is too long and not fully rendered on github.com, so either use:
+
+* https://cirosantilli.com/linux-kernel-module-cheat
+* https://cirosantilli.com/linux-kernel-module-cheat/index-split[]: split header version
+* <<build-the-documentation,build the docs yourself>>
 
 image::https://raw.githubusercontent.com/cirosantilli/china-dictatorship-media/master/Xinjiang_prisoners_sitting_identified.jpeg[width=800]
 

build-doc

@@ -32,21 +32,36 @@ from the README to example sources to GitHub rather than locally.
             link_target_script = 'link-target-github.rb'
         else:
             link_target_script = 'link-target-up.rb'
+        common_cmd = [
+            'bundle', LF,
+            'exec', LF,
+            'asciidoctor', LF,
+            '--attribute', 'docinfo=shared', LF,
+            '--failure-level', 'info', LF,
+            '--require', os.path.join(asciidoctor_dir, link_target_script), LF,
+            '--trace', LF,
+            '--verbose', LF,
+        ]
         exit_status = self.sh.run_cmd(
+            common_cmd +
             [
-                'asciidoctor', LF,
-                '--attribute', 'docinfo=shared', LF,
-                '--failure-level', 'info', LF,
-                '--require', os.path.join(asciidoctor_dir, link_target_script), LF,
                 '--out-file', self.env['readme_out'], LF,
-                '--trace', LF,
-                '--verbose', LF,
-            ] +
-            [
                 self.env['readme'], LF,
             ],
             out_file=self.env['build_doc_log'],
         )
+        if exit_status == 0:
+            exit_status = self.sh.run_cmd(
+                common_cmd +
+                [
+                    '-D', self.env['out_doc_dir'], LF,
+                    '-a', 'multipage-level=6', LF,
+                    '-b', 'multipage_html5', LF,
+                    '-r', 'asciidoctor-multipage', LF,
+                    self.env['readme'], LF,
+                ],
+                out_file=self.env['build_doc_multipage_log'],
+            )
 
         # Check that all local files linked from README exist.
         external_link_re = re.compile('^https?://')

common.py

@@ -53,8 +53,10 @@
 else:
     consts['out_dir'] = os.path.join(consts['root_dir'], 'out')
 consts['readme'] = os.path.join(consts['root_dir'], 'README.adoc')
+consts['out_doc_dir'] = os.path.join(consts['out_dir'], 'doc')
 consts['readme_out'] = os.path.join(consts['out_dir'], 'README.html')
 consts['build_doc_log'] = os.path.join(consts['out_dir'], 'build-doc.log')
+consts['build_doc_multipage_log'] = os.path.join(consts['out_dir'], 'build-doc-multipage.log')
 consts['gem5_out_dir'] = os.path.join(consts['out_dir'], 'gem5')
 consts['kernel_modules_build_base_dir'] = os.path.join(consts['out_dir'], 'kernel_modules')
 consts['buildroot_out_dir'] = os.path.join(consts['out_dir'], 'buildroot')

publish-gh-pages

@@ -10,7 +10,9 @@ git checkout master -- \
   _config.yml \
 ;
 cp out/README.html index.html
-git add index.html
+cp out/doc/* .
+mv README.html index.html
+git add .
 git commit --message "$(git log -n1 --pretty='%H' master)"
 git push
 git checkout -