Renders RakuDoc sources into an output format dependent on templates
SYNOPSIS
Overview
Command line invocation
RenderDocs utility
Docker image
Documentation
RenderTextify utility
Wrapping
Troubleshooting
Credits
• Clone the repository
▹ git clone https://github.com/finanalyst/rakuast-rakudoc-render.git
▹ cd rakuast-rakudoc-render
• Install using zef as follows (flag is important)
▹ zef install . -/precompile-install
Note that zef runs the tests in t/, and those cause compilation of the modules in the distribution.
To eliminate the possibility of RakuDoc errors, use
verify-rakudoc filename
where filename is a RakuDoc source. If necessary, .rakudoc will be appended.
Also a docker container is available as described in Docker image
This distribution is intended to provide several renderers from RakuDoc v2 into commonly used output formats. For those reading this file on finanalyst.github.io, the distribution can be found at Github repo.
The basic render engine is RakuDoc::Render, which renders a RakuDoc source into text for display on a terminal.
The Renderer class is designed to be extended to other output formats by subclassing.
It is easier to use [RenderDocs](RenderDocs utility), which handles output to different formats and saves to a file.
This software uses bleeding edge Rakudo, so look at troubleshooting below.
The RakuDoc documentation describes a command line invocation, which is described here, but [RenderDocs](RenderDocs utility) is recommended.
The canonical method for generating rendered text is possible using the Generic renderer and sends the output to STDOUT, so its best to pipe to a file, namely
RAKUDO_RAKUAST=1 raku --rakudoc=Generic rakudociem-ipsum.rakudoc > store-output
Some naive wrapping and width modification is possible using environment variables.
The file rakudociem-ipsum.rakudoc is the file for testing RakuDoc v2 compliance. An up-to-date copy can be obtained with:
bin/get-compliance-document
A copy of rakudociem-ipsum.rakudoc is also contained in resources/compliance-rendering, together with renderings of the file using the output renderers in this distribution.
In order to avoid environment variables, eg for Windows, a RakuDoc file can be rendered to Text using the [RenderTextify](RenderTextify utility). It avoids some installation problems, stores the output and offers some other output options, eg.
bin/RenderTextify rakudociem-ipsum
(the .rakudoc extension may be omitted if desired)
RenderDoc has several advantages over a raku invocation:
• Output to different formats is managed using the --format command line option:
▹ no --format or --format=md: generates a file in Markdown with an .md extension
▹ --format=HTML --single: generates a file in HTML, ending _singlefile.html, which can be opened directly in a browser without internet connection.
▹ --format=HTML: generates a file in HTML, ending .html, the HTML is intended for use with an internet connection and has a number of custom blocks.
• Simpler file specification
▹ By default, all the rakudoc sources from docs/ are rendered
▹ By default, all the output files are stored at the Current working directory
▹ The first word after the options (eg documents) is taken to be the file docs/documents.rakudoc
▹ The source location can be given with --src=... and the output with --to=...
Given these defaults, the following will render all the *.rakudocs in docs/ to <./*.md> in Markdown.
bin/RenderDocs
In order to get the command line options try
bin/RenderDocs -h
An example of rendering a single file, put the basename without .rakudoc as a string parameter, eg.
bin/RenderDocs README
In order to override the source and output defaults use --src and --to options, eg.
bin/RenderDocs --src='sources/' --to='rendered/' some-file
In order to get single file HTML, rather than markdown, and output it into rendered/
bin/Render --to='rendered' --html --single README
In order to get the possibilities offered by RakuDoc::To::HTML-Extra, including maps, graphs, themes and the Bulma CSS framework, use --format=html, eg.
bin/Render --format=html src=docs/plugins Graphviz
Two debug options --debug and --verbose are available and are described in Render.
The distribution contains a Dockerfile, which shows the installation steps needed. An image of a recent distribution can be found at docker.io/finanalyst/rakuast-rakudoc-render:latest
The docker image was designed for use as a github CI action. For example, place the following content in the file .workflows/GenerateDocs.yml in the root of a github repository:
name: RakuDoc to MD
on:
# Runs on pushes targeting the main branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
container-job:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
with:
persist-credentials: false
fetch-depth: 0
- name: Render docs/sources
uses: addnab/docker-run-action@v3
with:
image: finanalyst/rakuast-rakudoc-render:latest
registry: docker.io
options: -v ${{github.workspace}}/docs:/docs -v ${{github.workspace}}:/to
run: RenderDocs --src=/docs --to=/to --force
- name: Commit and Push changes
uses: Andro999b/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: 'main'
Then whenever commits are pushed to the repository, all new or modified documents in docs/ are rendered into Markdown and copied to the root of the repository (remember to git pull locally).
If you are reading this from the repo, an HTML version of the documentation can be found at finanalyst.github.io.
The two main documentation sources are:
• An overview of the generic renderer
• The templating system
The utility bin/RenderTexify can be called with a RakuDoc source and it saves the result directly to a file, rather than to STDOUT.
For example,
bin/RenderTextify rakudociem-ipsum
will produce the file
rakudociem-ipsum.rakudoc.text
The executable bin/RenderTexify can also be called with the flags test and pretty and the name of a file to render. The use case of these options is to see what templates receive from the rendering engine when developing new templates.
The file is output to text files with the flag and .text appended to the name. The file format .rakudoc is assumed, and added if missing.
For example,
bin/RenderTextify --pretty rakudociem-ipsum
will produce the file
rakudociem-ipsum.rakudoc.pretty.text
The text output will be naively wrapped (the algorithm is still being developed), either by setting the environment variable POSTPROCESSING=1 or using RenderTextify. For example,
POSTPROCESSING=1 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output
or
bin/RenderTextify --post-processing doc
If the environment variable WIDTH (--width) is also set, the text output will be wrapped to the value. WIDTH by default is set at 80 chars. To set at 70, use:
POSTPROCESSING=1 WIDTH=70 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output
or
bin/RenderTextify --post-processing --width=70 doc
The utility can also be used for debugging new templates. For more information, see the Render and Templates documents. To get all the debugging information, and information on the template for C-markup try
bin/RenderTextify --debug='All' --verbose='C-markup' doc
In order to get the RakuDoc render test file (rakudociem-ipsum) to work, a recent version of the Rakudoc compiler is needed, after v2024.07.
If the cannonical command raku invocation fails, perhaps with a message such as
===SORRY!===
This element has not been resolved. Type: RakuAST::Type::Simple
or
Out-of-sync package detected in LANG1 at r => Str=｢{ $!front-matter }｣
(value in braid: RakuAST::Class, value in $*PACKAGE: RakuAST::Class)
===SORRY!===
No such method 'IMPL-REGEX-QAST' for invocant of type 'RakuAST::Regex'
then try
bin/force-compile
This deletes the .precomp files in the current directory, and runs prove6 -I., which causes a recompilation of all the modules.
Richard Hainsworth aka finanalyst
Rendered from docs/README.rakudoc/README at 17:16 UTC on 2025-01-05
Source last modified at 17:15 UTC on 2025-01-05