txt: ## dist_zef-finanalyst-Rakuast-RakuDoc-Render.md
  # RakuDoc renderer
  
  ```
  Renders RakuDoc sources into an output format dependent on templates
  
  ```
  
  ---
  
  ## Table of Contents
  
  [SYNOPSIS](#SYNOPSIS)  
  [Overview](#Overview)  
  [Command line invocation](#Command_line_invocation)  
  [RenderDocs utility](#RenderDocs_utility)  
  [Docker image](#Docker_image)  
  [Documentation](#Documentation)  
  [RenderTextify utility](#RenderTextify_utility)  
  [Wrapping](#Wrapping)  
  [Troubleshooting](#Troubleshooting)  
  [Credits](#Credits)
  
  ## SYNOPSIS
  
    • 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
  
  ## Overview
  
  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](https://github.com/finanalyst/rakuast-rakudoc-render).
  
  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](Troubleshooting).
  
  ## Command line invocation
  
  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](Wrapping) is possible using environment variables.
  
  The file [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:
  
  ```
  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)
  
  ## RenderDocs utility
  
  *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](Render.md).
  
  ## Docker image
  
  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/push@v1.3
                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).
  
  ## Documentation
  
  If you are reading this from the repo, an HTML version of the documentation can be found at [finanalyst.github.io](https://finanalyst.github.io).
  
  The two main documentation sources are:
  
    • [An overview of the generic renderer](https://finanalyst.github.io/Render)  
    • [The templating system](https://finanalyst.github.io/Templates)
  
  ## 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
  
  ```
  
  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
  
  ```
  
  ## 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 `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.
  
  ## Credits
  
  Richard Hainsworth aka finanalyst
  
  ## VERSION
  
  v0.20.0
  
  ---
  
  ---
  
  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
  