Rakefile for generating doc.scheme.org Peter Lane (30 Jul 2022 11:30 UTC)
Re: Rakefile for generating doc.scheme.org Lassi Kortela (31 Jul 2022 06:55 UTC)

Rakefile for generating doc.scheme.org Peter Lane 30 Jul 2022 11:29 UTC

Hi,

I've been following the progress of scheme.org for a while, and am glad
to see the main page is now 'live'! One thing I noticed is that the
guide files are not integrated into the main design - I've adapted
something I use to build my own website, which may be helpful.

I use a rakefile to convert all the .adoc guide files into html,
including the scheme.org header/footer information around them, so they
appear more integrated into the website.

Additionally, the rakefile calls asciidoctor with the rouge
source-highlighter (also implemented in Ruby), which makes the source
code look prettier.

If you want to try this, download the code from:
https://github.com/pcl-code/guide

You need ruby.

Install asciidoctor and rouge:
 > gem install asciidoctor
 > gem install rouge

Then use the rakefile:
 > rake -T
rake build   # build web site afresh
rake clean   # clean up directory
rake show    # show web www - port 8000
rake update  # update revised or new files only
 > rake build
 > rake show

And admire the pages in your browser at 'localhost:8000/guide'

'rake build' creates the files in www, including the doc.scheme.org
index page (rather like the www.sh script).

To make this self-contained, I've added the schemeorg.css file (from the
website) and a syntax.css file (generated from rouge). I have not
updated every guide to use source highlighting, but try 'esoterica' as
an example.

The list of guides is automatically completed in the index page, so new
guides can be added easily by dropping in a new .adoc file and running
'rake update'.

If this is useful, or potentially useful after some changes, I can work
on it further and send a pull request or whatever is convenient. Let me
know what you think.

-- Peter

Peter Lane
https://peterlane.info/scheme