Help language development. Donate to The Perl Foundation

Collection-Raku-Documentation zef:finanalyst last updated on 2023-01-15

doc/README.rakudoc
=begin pod

=TITLE Collection-based Raku Documentation

=DESCRIPTION Distribution to set up Raku Documentation website.

=AUTHOR Richard Hainsworth, aka finanalyst

This Module creates a local website of the Raku documentation. It pulls together information held
in several other distributions. The main content of this distribution is the C<Raku-Doc> utility.
It is intended to be as simple as possible. But the documentation system is large. The following
contain other requirements.

=item The documentation files are held in a github repository that is maintained and updated by the
Raku community. C<Raku-Doc> needs to have a local clone of the repository. It can be used to refresh
the documents automatically.

=item C<Raku-Doc> uses Collection and Raku::Pod::Render to link all the Rakudoc (aka Pod6) files together.
So C<Collection> needs to be installed, which will install C<Raku::Pod::Render>. By installing
C<Raku-Pod-Render> a user can then use C<Pod::To::HTML2> to render individual C<.rakudoc / .pod6> files
into HTML, or C<Pod::To::MarkDown2> to render them into C<.md> files.

=item C<Collection> requires over a dozen plugins, which are automatically refreshed from a github repository
by C<Raku-Doc>.

=item The Raku documentation system can currently be visualised in two ways:
=item2 using the original web design started by Moritz Lenz (using the mode Website) - currently the default.
=item2 using a new design by OgdenWebb (using the mode OgdenWebb).

=item 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.

=item A website contains templates and structure documents, which describe the website
into which the Raku documentation fit. This content is also held in a separate repository. This is intended
to keep the development of plugins separate from the structure documents and templates, and separate from
the Raku documentation content.

=head1 Installation

    zef install Collection-Raku-Documentation

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

See L<Highlighting> for installation of highlighter.

=head1 Raku-Doc

On a Linux based distributions, C<Raku-Doc> depends on C<git> and C<unzip>, 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 C<localhost:30000>, and produce a
progress status bar for the longer stages.

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

This sets up a Collection directory by downloading the Website mode from
github, then installs the Collection plugins.

By default the C<Raku/doc> repository (containing all the Raku documentation files)
will be created in the next step as B<local_raku_docs>.

If a user wants to clone the Raku docs repository elsewhere
or has an existing clone of the Raku repository, then the non-default path needs to be put into the
config.raku file in the C<sources-obtain> and C<sources-refresh> keys. See the documentation
for the C<Collection> distribution for more information.

At the next invocation of B<Raku-Doc>, the documentation source will be cloned, cached,
and rendered.

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

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

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

The Raku Documentation source files are regularly updated.
The B<Website> mode is configured to pull the latest versions
of the source files into the Collection whenever C<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.

The Website mode files and plugins are being actively developed, so newer versions may be
available. New versions of the plugins are automatically called on each invocation of
Raku-Doc. To get new versions of the Website mode files (sources and additional plugins), use

    Raku-Doc Update

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

B<Collection-Raku-Documentation> is set up with the default C<mode> called B<Website>.

The more contemporary web design by Ogden Webb is in a mode call B<OgdenWebb>. It is generated thus:

    Raku-Doc OgdenWebb

It can be made the default by changing the C<mode> key in the top-level C<config.raku> file.

=head1 Raku-Doc as a wrapper for Collection::collect

With the exception of 'Init' and 'Update', C<Raku-Doc> can be called with all the options
listed for C<Collection::collect>.

More information about these options is given in the Documentation for C<Collection>.

=head2 More contemporary web site.

A more contemporary web design by Ogden Webb is now included. It is generated by running

    Raku-Doc OgdenWebb

=head2 In the future (not now)

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

    Raku-Doc Book

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

=head1 Enabling Cro App

A Cro App is included that will run the website automatically by running C<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 C<Raku-Doc> without options will now serve the documentation files locally on port 3000.
So point your browser at C<localhost:3000>

=head1 Highlighting

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

For someone who has not installed C<node> or C<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, B<after the default installation of Raku::Pod::Render>, highlighting can be
enabled by running the following in a terminal:

    raku-render-install-highlighter

=head1 Problems

Collection is still being actively developed.

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

=head1 Copyright and License

(c) Richard N Hainsworth, 2021-2022

B<LICENSE> Artistic-2.0
=end pod