Raku Documentation

The Collection files for the Raku Documentation site.

Table of Contents

Installation
Building the documentation locally
Options for build-site
Directory naming
Deprecated URLs
Plugins and Templates
Working on Collection plugins
Deployment of website
Updates to the README

---

(The README.md version is generated from repo_docs/README.rakudoc)

Installation

These instructions assume a Unix-like system.

This repo can be cloned and the main dependencies can be installed with

zef install . --deps-only

in the cloned directory. There are a couple of C libraries that may need to be installed as well, such as OpenSSL and LibArchive (make sure to install the -dev versions).

Cro is needed for serving the rendered files locally. You may wish to install it separately.

We have reports of some users missing a curl dependency despite having curl available from the command line. If this happens to you, please add --exclude="curl" to the zef command.

If you are missing dot, install the graphviz package for your OS.

Building the documentation locally

Generic build steps:

• clone this repo to raku-doc-website/

  • No need to clone the Raku documentation sources at github.com/raku/doc/doc to local_raku_docs/doc/ as this is done automatically by the final step. However, if you already have a local raku/doc repo, then change the relevant key in config.raku. It should be intuitive what is required.

  • Note also the '_' character in the default directory name. This is important for Collection if the document sources are under the raku-doc-website because Collection treats directories without '_' as mode directories.

• assume the rendered html will be built in rendered_html

All these names can be changed by changing the relevant parts of the config.raku file

Now run

bin_files/build-site

If Cro and Cro::HTTP have been installed, then build-site will automatically launch a Cro app and the whole website will be served on localhost:30000.

Options for build-site

There are many options for build-site, which is a thin wrapper around the collect sub in Collection.

However, you can run

bin_files/build-site --help

or

bin_files/build-site --more-help

for a quick overview.

Directory naming

As mentioned in the items above, Collection expects a sub-directory that does not include a '_' in its name to be a 'Mode'.

For this reason, documentation sources for this repo are in repo_docs and the binaries are in bin_files.

This may eventually prove unnecessary, but it is a reasonable convention is kept for the time being.

Further, in the future, another Mode may be useful in this repository in due course that generates an epub output.

Deprecated URLs

Occasionally, file names change. This would cause a 404 error if an external webpage, e.g. someone's blog, has a link to a changed file name. To overcome this, a mapping file deprecated-urls is kept in Website/plugins/raku-doc-setup. The plugin adds this file to rendered_html/assets/, and the Caddy system rewrites routes from the deprecated name to the working alternative.

Plugins and Templates

Collection is designed to handle multiple Modes, and for plugins to be contributed in a similar way to Raku Modules. However, for the Raku documentation system, it seems pragmatic at the start for the plugins to be tailored specifically for this site.

Consequently, the plugins are directly copied into the OgdenWebb directory, rather than using Collection's refresh functionality. This comment may seem odd but I include it to preclude questions that will arise when reading the documentation for Collection.

The Templates were originally developed to mimic Moritz Lenz's Raku site (the one we are used to). Relevant template keys are modified in the ogdenwebb plugin. I would expect this to change over time, and for the default templates to change to the OgdenWebb templates. But I would suggest this is done incrementally.

Working on Collection plugins

Collection uses plugins - they can be found under the directory Website/plugins/ - which contain both callables that set up templates, associate CSS (defined using SCSS) with classes etc, and manipulate data.

Whilst the best way to work on the plugins is, as described below, to use the dedicated plugins distribution, it increases the learning curve and also means that there is an extra step in directly importing Collection plugins to the Raku Documentation repo (as mentioned above, the 'refresh' functionality of Collection is not used here).

However, to make development here easier, there are three utilities which directly affect this distribution:

• update-css which is a Bash file and takes the name of a plugin as its argument.

• bin_files/test-all-plugins This runs all the test files in all the plugins

• bin_files/build-site By default this will

  • refresh the documents from the contents repository at github/raku/docs

  • cache any changes to the source documents

  • render all the source documents

However, if a change to a plugin has been made and it can be seen with only one or two source files, then it is quicker to use the build-site option with-only, e.g.

bin_files/build-site --with-only='language.rakudoc operators'

There is a file in Website/structure-sources/language.rakudoc and a file in the doc sources called doc/language/operators.pod6. Any element in the space delimited list following --with-only that matches a source file name will be rendered.

A better way, though, to tweak or add new plugins and see how they affect the website, is to install the distribution raku-collection-plugin-development.

Deployment of website

The main branch is deployed to docs-dev.raku.org every two hours. Look there to see your changes after they're merged.

The production version of the website is docs.raku.org. Administrators update it manually, after verifying things look good on dev.

Updates to the README

The markdown in the root of the project can be updated with this command

raku --doc=MarkDown2 repo_docs/README.rakudoc > README.md

---

Rendered from at 2024-11-12T02:43:57Z