Help language development. Donate to The Perl Foundation
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
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.
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
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
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:
On a Linux based distributions,
Raku-Doc depends on
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
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
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-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
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,
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.
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
Raku-Doc without options will now serve the documentation files locally on port 3000. So point your browser at
Collection is still being actively developed.
sources-refreshkey set to a git pull stanza, Raku-Doc teminates after a git pull. Workaround: run
(c) Richard N Hainsworth, 2021-2022
Rendered from README at 2022-08-11T00:14:33Z