Collection-based Raku Documentation

Description Collects the Raku Documentation's content sources existing in github repo, creates a static html collection for serving using Cro.

Author Richard Hainsworth, aka finanalyst

Installation
Raku-Doc
In the future (not now)
Enabling Cro App
Problems
Copyright and License

This Module provides a local website of the Raku documentation that can be made available via a browser at localhost:3000 . The Module uses Collection and Raku::Pod::Render to link all the Rakudoc (aka Pod6) files together.

The website is intended to be served locally with a Cro app. Since making Cro a dependency can cause problems in a testing environment, the META6.json does not have Cro as a dependency. If Cro::HTTP is not installed, the completion plugin will exit with a note.

The Website also demonstrates some of the custom blocks possible using Raku::Pod::Render.

Installation

zef install Collection-Raku-Documentation

This installs the Collection (and other) dependencies and the Raku-Docs executable. These in turn install the the other main distributions and Raku::Pod::Render. By default Raku::Pod::Render does not install the highlighter automatically because node.js and npm are required.

The default highlighter at present is a Node based toolstack called atom-perl-highlighter. In order to install it automatically, Raku::Pod::Render requires an uptodate version of npm. The builder is known not to work with node.js > ****v13.0> and npm > v14.15.

For someone who has not installed node or npm before, or for whom they are only needed for the highlighter, the installation is ... confusing. It would seem at the time of writing that the easiest method is:

# Using Ubuntu
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs

Then, after the default installation of Raku::Pod::Render, highlighting can be enabled by running the following in a terminal:

raku-render-install-highlighter

Raku-Doc

On a Linux based distributions, Raku-Doc depends on git and unrar, which typically are installed by default, to get and unpack other files.

Under Linux, in a terminal, the following will lead to the installation of a local copy of Raku docs and start a Cro app that will make the HTML documentation available in a browser at localhost:30000, and produce a progress status bar for the longer stages.

mkdir ~/raku-local
cd raku-local
Raku-Doc Init

This sets up the Collection directory, and installs the dependencies.

If the Website mode has been corrupted, or a new version is available, then

Raku-Doc Refresh

will prompt you for which resource to refresh. If one is chosen, the others will be left unchanged.

It does not clone a copy of the Raku/doc repository because an existing version may be available on the system.

Consequently, the user needs to clone the Raku docs repository using something like git clone https://github.com/Raku/doc.git raku-docs. Then the path used can be put into the config.raku file in the sources-refresh key. Once the raku-docs are ready, the INIT stage is complete.

For example, to render the full Raku Docs, the following would work, where raku-local is a local directory.

- raku-local
    - raku-docs # this is generated by the git clone command
    - Website # this is generated by runnng 'Raku-Doc Init' in raku-local
    config.raku # as Website

After the Init stage, calling Raku-Doc without any other options implies the mode Website with default options.

The Raku Documentation source files are regularly updated. The Website mode is configured to pull the latest versions of the source files into the Collection whenever Raku-Doc is run, which then updates the cache for any sources that have changed, and then re-render all the html files that are affected. These stages are automatically called by running Raku-Doc with the config defaults given.

Raku-Doc can be called with other options, which are described in the Collection documentation.

Collection-Raku-Documentation is set up with the default mode called Website. Raku-Doc just calls collect and passes on to collect all of its arguments, with the exception of the string Init, which Raku-Doc traps so that processing can stop before calling collect.

In the future (not now)

If Raku-Doc is called with a string other than 'Init', 'Refresh' or 'Website', then the string is interpreted as another Mode, with its own sub-directory and Configuration for the collection. For example,

Raku-Doc Book

would create the collection output defined by the configuration in the sub-directory Book/config/. This design is to allow for the creation of different Collection outputs to be defined for the same content files.

Enabling Cro App

A Cro App is included that will run the website automatically by running Raku-Doc. The Cro App is called using a plugin that runs after the html files have been refreshed. The Cro App is called at completion (see Collection documentation). It contains a test to see if Cro::HTTP is installed.

Since installing Cro can cause testing problems, this distribution does not have Cro::HTTP as a dependency.

Cro in installed using zef as

zef install Cro::HTTP

Running Raku-Doc without options will now serve the documentation files locally on port 3000. So point your browser at localhost:3000

Problems

Collection is still being actively developed.

When running Raku-Doc with a sources-refresh key set to a git pull stanza, Raku-Doc teminates after a git pull. Workaround: run Raku-Doc again.

Copyright and License

LICENSE Artistic-2.0

Rendered from README at 2022-08-11T00:14:33Z