Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/finanalyst/rakuast-rakudoc-render

Renders RakuDoc from RakuAst statement list
https://github.com/finanalyst/rakuast-rakudoc-render

Last synced: 17 days ago
JSON representation

Renders RakuDoc from RakuAst statement list

Awesome Lists containing this project

README 

        

# RakuDoc renderer



	Renders RakuDoc sources into an output format dependent on templates



----



## Table of Contents



SYNOPSIS   

Overview   

Documentation   

RenderTextify utility   

Wrapping   

RenderDocs utility   

Troubleshooting   

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. 



----



## 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](Troubleshooting). 



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](Wrapping) is possible using environment variables. 



The file [rakudociem-ipsum.rakudoc](https://github.com/Raku/RakuDoc-GAMMA/blob/main/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](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) 



Rendering into the other output formats provided in this distribution can be done using [RenderDocs](RenderDocs_utility). 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](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

```



----



## 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

```

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



----



----



Rendered from docs/docs/README.rakudoc at 21:43 UTC on 2024-09-22



Source last modified at 21:42 UTC on 2024-09-22