Simple and customisable module for rendering RakuDoc v2 to Markdown.
To render a RakuDoc source, eg. some-docs.rakudoc, into some-docs.md, either use the terminal command
RAKUDO_RAKUAST=1 raku --rakudoc=Markdown some-docs.rakudoc > some-docs.md
or (see below for more detail)
bin/RenderDocs some-docs
There is a section on Troubleshooting in the general README file if this fails.
Markdown representation of documentation is widespread, so a simple conversion (rendering) of the RakuDoc v2 into Markdown is useful, even though Markdown is intended to be viewed as HTML.
The module can be customised by setting an Environment variable to a template file. More detail on customising.
The general README file should be read first.
For this description, it is assumed that the RakuAST::RakuDoc::Render distribution is NOT installed using zef, although it can be. Consequently, all commands are assumed to be inside the repo directory root.
All output from Rakuast::RakuDoc::Render modules is generated through templates. These templates can be added to, without overriding the previous templates, (see Templates for detail).
If a file exists in the local directory called new-temp.raku and conforms to the requirements described in Templates, then the templates in it will be added to the generic Markdown templates as follows:
MORE_MARKDOWN=new-temp.raku RAKUDO_RAKUAST=1 raku --rakudoc=Markdown some-docs.rakudoc > store.md
For instance if the contents of new-temp.raku is
%(
final => -> %prm, $tmpl { "# Customisation message\n\n" ~ $tmpl.prev }
)
Then after running the command above, store.md will contain a new title at the top, followed by the remainder of the Markdown as rendered before the new template was added.
Some notes:
The template final is the last one that glues all the documentation together into a string.
$tmpl.prev is call to the previous version of final with all the parameters passed on.
All the generic templates are tabulated with comments.
A utility called RenderDocs accompanies the distribution. It is assumed that documentation sources in RakuDoc are contained in the sub-directory docs/ and that Markdown versions are required in the working directory. If any RakuDoc source has a modified date later than the current version of the Markdown output, then the Markdown file is updated.
Usage
bin/RenderDocs
More granularity can be obtained by specifying a single file and a to destination, eg.
bin/RenderDocs --to=README docs/README
Here, there must be a file docs/README.rakudoc, which is rendered to the current working directory as README.md.