RakuDoc renderer

Renders RakuDoc sources into an output format dependent on templates

SYNOPSIS
Overview
Documentation
RenderTextify utility
Wrapping
RenderDocs utility
Troubleshooting
Credits

SYNOPSIS

• Clone the repository and submodule
▹ git clone https://github.com/finanalyst/rakuast-rakudoc-render.git rrr

▹ cd rrr && git submodule init

▹ git submodule update

• 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.

Overview

This distribution is intended to provide several renderers from RakuDoc v2 into commonly used output formats.

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.

This is software using bleeding edge Rakudo, so look at troubleshooting below.

Using the Generic renderer, the canonical method for generating rendered text is possible (which sends output to STDOUT, so 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. It 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. 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)

Rendering into the other output formats provided in this distribution can be done using RenderDocs. By default, sources are located in docs/ and rendered to the current working directory into MarkDown, eg.,

bin/RenderDocs README

Documentation

All documentation can be found at finanalyst.github.io.

The two main documentation sources are:

• An overview of the generic renderer

• The templating system

RenderTextify utility

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

Wrapping

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

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

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

RenderDocs utility

RenderDoc is similar to RenderTextify, but uses the other formats in this distribution, namely

• .md - Markdown (default)

• -singlefile.html - HTML that can be opened directly in a browser without internet connection.

• .html - HTML that is intended for use with an internet connection

By default, the utility renders all the rakudoc sources from docs/ and outputs them in markdown to the current working directory, eg.

bin/RenderDocs

In order to get the useage try

bin/RenderDocs -h

In order to render 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

bin/Render --to='rendered' --html README

In order to get the possibilities offered by RakuDoc::To::HTML-Extra, including maps, graphs, themes and the Bulma CSS framework, use --html and --extra, eg.

bin/Render --html --extra Graphviz

The html variants allow for --debug and --verbose.

Troubleshooting

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 above fails, perhaps with a message such as

===SORRY!===
    This element has not been resolved. Type: RakuAST::Type::Simple

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.

Credits

Richard Hainsworth aka finanalyst

VERSION

v0.4.0

Rendered from docs/docs/README.rakudoc at 11:06 UTC on 2024-08-17

Source last modified at 11:05 UTC on 2024-08-17

finanalyst / rakuast-rakudoc-render

readme