=begin rakudoc :type<fundamental>
=TITLE RakuDoc renderer

=SUBTITLE Renders RakuDoc sources into an output format dependent on templates
=for AUTHOR :hidden
Richard Hainsworth aka finanalyst

=for VERSION :hidden
v0.20.0

=begin SYNOPSIS
=item Clone the repository
=item2 C<git clone https://github.com/finanalyst/rakuast-rakudoc-render.git>
=item2 C<cd rakuast-rakudoc-render>
=item Install using zef as follows (flag is important)
=item2 C<zef install . -/precompile-install>

Note that C<zef> runs the tests in C<t/>, and those cause compilation of the
modules in the distribution.

To eliminate the possibility of RakuDoc errors, use
=for code :allow<R>
verify-rakudoc R<filename>

where R<filename> is a RakuDoc source. If necessary, I<.rakudoc> will be appended.

Also a docker container is available as described in L< Docker image | #Docker image >
=end SYNOPSIS

=head Overview

This distribution is intended to provide several renderers from RakuDoc v2 into commonly used
output formats. For those reading this file on I<finanalyst.github.io>, the distribution can
be found at L<Github repo|https://github.com/finanalyst/rakuast-rakudoc-render>.

The basic render engine is C<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 L<RenderDocs|#RenderDocs utility>, which handles output to different formats and saves to a file.

This software uses bleeding edge Rakudo, so look L<at troubleshooting below|#Troubleshooting>.

This software uses C<citeproc> and C<pandoc> by JohnMacFarlane, and <BibUtils> by Chris Putnam. These all need to be
installed if C< Q<> > markup is used. C<citeproc> and C<pandoc> are Haskell programs and can typically be installed
using your OS's package manager, or compiled using C<cabal>. C<BibUtils> are C programs and can be installed with a
package manager or compiled.

The Citations module expects I<Citation style> files to be located at C</usr/share/csl>, and hundreds of styles
are available. Install using
    sudo git clone https://github.com/citation-style-language/styles.git /usr/share/csl

=head Command line invocation

The RakuDoc documentation describes a command line invocation, which is described here, but
L<RenderDocs|#RenderDocs utility> is recommended.

The B<canonical method> for generating rendered text is possible using the I<Generic> renderer
and sends the output to STDOUT, so its best to pipe to a file, namely

=for code :lang<text>
RAKUDO_RAKUAST=1 raku --rakudoc=Generic rakudociem-ipsum.rakudoc > store-output

Some L<naive wrapping and width modification|#Wrapping> is possible using environment variables.

The file L<rakudociem-ipsum.rakudoc|https://github.com/Raku/RakuDoc-GAMMA/blob/main/compliance-document/rakudociem-ipsum.rakudoc>
is the file for testing RakuDoc v2 compliance. An up-to-date copy can be obtained with:

=for code :lang<text>
bin/get-compliance-document

A copy of C<rakudociem-ipsum.rakudoc> is also contained in C<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 L<RenderTextify|#RenderTextify utility>. It
avoids some installation problems, stores the output and offers some other output options, eg.

=for code  :lang<text>
bin/RenderTextify rakudociem-ipsum

(the .rakudoc extension may be omitted if desired)

=head RenderDocs utility

I<RenderDoc> has several advantages over a C<raku> invocation:
=item Output to different formats is managed using the C<--format> command line option:
=item2 I<no --format> or C<--format=md>: generates a file in Markdown with an K<.md> extension
=item2 C<--format=HTML --single>: generates a file in HTML, ending K<_singlefile.html>, which can be opened directly in a browser without internet connection.
=item2 C<--format=HTML>: generates a file in HTML, ending K<.html>, the HTML is intended for use with an
internet connection and has a number of custom blocks.
=item Simpler file specification
=item2 By default, B<all> the I<rakudoc> sources from C<docs/> are rendered
=item2 By default, all the output files are stored at the I<Current working directory>
=item2 The first word after the options (eg R<documents>) is taken to be the file B<docs/documents.rakudoc>
=item2 The source location can be given with C<--src=...> and the output with C<--to=...>

Given these defaults, the following will render all the I<*.rakudocs> in I<docs/> to <./*.md> in Markdown.

=for code :lang<text>
bin/RenderDocs

In order to get the command line options try
=for code :lang<text>
bin/RenderDocs -h

An example of rendering a single file, put the basename without I<.rakudoc> as a string parameter, eg.
=for code :lang<text>
bin/RenderDocs README

In order to override the source and output defaults use C<--src> and C<--to> options, eg.
=for code :lang<text>
bin/RenderDocs --src='sources/' --to='rendered/' some-file

In order to get single file HTML, rather than markdown, and output it into I<rendered/>
=for code :lang<text>
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 C<--format=html>, eg.
=for code :lang<text>
bin/Render --format=html src=docs/plugins Graphviz

Two debug options C<--debug> and C<--verbose> are available and are described in L<Render|Render.*>.

=head Docker image

The distribution contains a C<Dockerfile>, which shows the installation steps needed. An image
of a recent distribution can be found at C<docker.io/finanalyst/rakuast-rakudoc-render:latest>

The docker image was designed for use as a I<github CI action>. For example, place the following
content in the file C<.workflows/GenerateDocs.yml> in the root of a I<github> repository:
=begin code
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/push@v1.3
              with:
                github_token: ${{ secrets.GITHUB_TOKEN }}
                branch: 'main'
=end code

Then whenever commits are pushed to the repository, all new or modified documents in B<docs/> are
rendered into Markdown and copied to the root of the repository (remember to C<git pull> locally).

Another set of docker images are available with Raku, Cro and Rakuast::RakuDoc::Render, namely
=item C<docker.io/finanalyst/raku-cro-base> - just Raku and Cro
=item C<docker.io/finanalyst/raku-cro-rrr-base> - the non-Raku dependencies and Rakuast::RakuDoc::Render

These are intended for developing software that need Rakuast::RakuDoc::Render, and contain all the
tools for additional development.

Finally, there are two docker images that embed Rakuast::RakuDoc::Render in a web-based editor.
=item C<docker.io/finanalyst/browserR-editor> - this is intended for running in a local docker container
=item C<docker.io/finanalyst/rakudoc_browser> - this is intended to be run on the web behind something like Apache.

=head Documentation

If you are reading this from the repo, an HTML version of the documentation can be found
at L<finanalyst.github.io| https://finanalyst.github.io>.

The two main documentation sources are:
=item L<An overview of the generic renderer|https://finanalyst.github.io/Render>
=item L<The templating system|https://finanalyst.github.io/Templates>

=head RenderTextify utility

The utility C<bin/RenderTexify> can be called with a RakuDoc source and it saves the
result directly to a file, rather than to STDOUT.

For example,
=for code  :lang<text>
bin/RenderTextify rakudociem-ipsum

will produce the file
=for code :lang<text>
rakudociem-ipsum.rakudoc.text

The executable C<bin/RenderTexify> can also be called with the flags C<test> and C<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 C<.text>
appended to the name. The file format C<.rakudoc> is assumed, and added if missing.

For example,
=for code :lang<text>
bin/RenderTextify --pretty rakudociem-ipsum

will produce the file
=for code :lang<text>
rakudociem-ipsum.rakudoc.pretty.text

=head 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,
=for code :lang<text>
POSTPROCESSING=1 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output

or
=for code :lang<text>
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:
=for code :lang<text>
POSTPROCESSING=1 WIDTH=70 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output

or
=for code :lang<text>
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<C-markup> try
=for code :lang<text>
bin/RenderTextify --debug='All' --verbose='C-markup' doc

=head1 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 C<raku> invocation fails, perhaps with a message such as
=for code :lang<text>
===SORRY!===
This element has not been resolved. Type: RakuAST::Type::Simple

or
=begin code :lang<text>
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'
=end code

then try
=for code :lang<text>
bin/force-compile

This deletes the C<.precomp> files in the current directory, and runs C<prove6 -I.>,
which causes a recompilation of all the modules.

=place semantic:AUTHOR :caption<Credits>

=place semantic:VERSION :!toc

=end rakudoc