Renders RakuDoc sources into an output format dependent on templates
git clone https://github.com/finanalyst/rakuast-rakudoc-render.git
cd rakuast-rakudoc-render
zef install . -/precompile-install
Note that zef runs the tests in t/, and those cause compilation of the modules in the distribution.
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. An uptodate 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. 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
All documentation can be found at finanalyst.github.io.
The two main documentation sources are:
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
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 --single 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 Graphviz
The html variants allow for --debug and --verbose, which are described in Render.
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
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.