Skip to content
🦋 Raku documentation (tools and docs)
Raku JavaScript CSS Makefile Shell Perl Other
Branch: master
Clone or download

Latest commit

JJ Merge pull request #3447 from uzluisf/master
Clarify description of reduce sub/method for Any and List
Latest commit 0af36d0 May 31, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Eliminates annoying progress bars, refs #2983 Aug 31, 2019
.github whitespace May 6, 2020
assets Update IRC channel name to #raku in link's content Jan 5, 2020
bin Use full path to rakudo, don't rely on $PATH lookup May 25, 2020
doc
highlights Changes URL closes #3106 Nov 30, 2019
html Revert accidental push to the wrong repository Sep 23, 2019
lib Fix previous, and while here, split TEST_FILES on any whitespace Apr 12, 2020
resources/i18n Update Chinese translation May 25, 2020
t Move p6doc tests to xt May 27, 2020
template Changes URL closes #3106 Nov 30, 2019
util Do not use a local(?) git alias Apr 12, 2020
writing-docs Update links May 22, 2020
xt Set the TERM environment variable's value in xt/p6doc-blackbox.t May 28, 2020
.dockerignore Fixed to get the dockerfile working Dec 27, 2018
.gitignore 🙈 Apr 19, 2020
.travis.yml Disables binary environment from matrix, refs #2859 Jul 19, 2019
Build.pm6 pm → pm6 Jul 20, 2018
CONTRIBUTING.md Rename: Perl 5 -> Perl (util) Mar 22, 2020
CREDITS Replaces repo name #3101 Nov 29, 2019
Dockerfile Replaces repo name #3101 Nov 29, 2019
LICENSE No more trailing whitespace (EVERYWHERE!) May 20, 2016
META6.json Add the substitute of Pod::Convenience to start moving it out Dec 6, 2019
Makefile Clean up/improve Makefile May 7, 2020
README.md Fix typo & removed extra blank lines May 25, 2020
app-start Make dev app watch for changes in search.js Apr 27, 2018
app.pl Changes permissions closes #2978 Aug 27, 2019
cpanfile For the time being, pins that version refs #2993 Aug 31, 2019
shippable.yml zef can't upgrade itself Jun 12, 2019
type-graph.txt Document Metamodel::DefiniteHOW Apr 9, 2020

README.md

Official Documentation of Raku

Build Status artistic Run Status CircleCI

An HTML version of this documentation can be found at https://docs.raku.org/ and also at rakudocs.github.io (which is actually updated more frequently). This is currently the recommended way to consume the documentation.

There is also a command line tool called p6doc, which you can use to browse the documentation once it's installed (see below).

This documentation is updated frequently to a GitHub mirror https://rakudocs.github.io but that might be out of sync with the official one.

Docker container

This documentation is also published as the jjmerelo/perl6-doc Docker container. It includes a copy of the web published on port 3000, so you can run it with:

docker run --rm -it -p 3000:3000 jjmerelo/perl6-doc

or

docker run --rm -it -p 31415:3000 jjmerelo/perl6-doc

in case you want it published somewhere else. You can direct your browser to http://localhost:3000 (or 31415, as the case may be).

README in other languages

Install p6doc

This module is available via the Raku module ecosystem. Use:

$ zef install p6doc

to install the "binaries" and make them available in your binaries execution path.

Note: Please note that, due to changes in the parsing of Pod6, this will fail in versions of Raku older than 2018.06. Please upgrade to that version, or install using --force.

Use p6doc

With a Rakudo rakudo executable in the PATH, try:

$ ./bin/p6doc Str

to see the documentation for class Str, or:

$ ./bin/p6doc Str.split

to see the documentation for method split in class Str. You can skip the ./bin part if you have installed it via zef. You can also do:

$ p6doc -f slurp

to browse the documentation of standard functions (which, in this particular case, will actually return multiple matches, which you can check individually). Depending on your disk speed and Rakudo version, it might take a while.


Building the HTML documentation

The documentation can be rendered to static HTML pages and/or served in a local web site. This process involves creating a cache of precompiled documents, so that generation after the first time is sped up.

Building the documentation has a number of prerequisites, which is might you might not want to do it yourself. However, if you need a local copy of the HTML documentation, please download it by cloning https://github.com/rakudocs/rakudocs.github.io

These are the prerequisites you need to install to generate documentation.

  • perl 5.20 or later
  • node 10 or later.
  • graphviz.
  • Documentable.

Please follow these instructions (in Ubuntu) to install them

sudo apt install perl graphviz # perl not installed by default in 18.04
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt-get install -y nodejs
cpanm --installdeps .
zef install Documentable

You can install perl and node any way you want, including version managers, as long as they're available to run from the command line.

This should install all needed requisites, now you can clone this repository and start building process:

git clone https://github.com/Raku/doc.git # clone the repo
cd doc # move to the clone of the repo
make for-documentable # Generates CSS and JS, installs highlighting modules
documentable start -a -v --highlight # Builds cache and generates pages.

You need to do this only the first time to build the cache. When there's some change in the source (done by yourself or pulled from the repo),

documentable update

will re-generate only affected pages.

Documentation will be generated in the html subdirectory. You can use it pointing any static web server at that directory, or use the development server based on Mojolicious using

make run

This will serve the documentation in port 3000.

nginx configuration

Latest version of the generated documentation consists only of static HTML pages. All pages are generated with .html at the end; however, most internal links don't use that suffix. Most web servers (for instance, the one that serves with GitHub pages) will add it automatically for you. A bare server will not. This is what you have to add to the configuration to make it work:

    location / {
        try_files $uri $uri/ $uri.html /404.html;
    }

This will rewrite the URLs for you. Equivalent configuration might have to be made in other server applications.


Help Wanted!

Raku is not a small language, and documenting it and maintaining that documentation takes a lot of effort. Any help is appreciated.

Here are some ways to help us:

  • Add missing documentation for classes, roles, methods or operators.
  • Add usage examples to existing documentation.
  • Proofread and correct the documentation.
  • Tell us about missing documentation by opening issues on Github.
  • Do a git grep TODO in this repository, and replace the TODO items by actual documentation.

Issues page has a list of current issues and documentation parts that are known to be missing and the CONTRIBUTING document explains briefly how to get started contributing documentation.


Some notes:

Q: Why aren't you embedding the docs in the CORE sources?
A: Several reasons:

  1. This documentation is intended to be universal with respect to a given version of the specification, and not necessarily tied to any specific Raku implementation.
  2. Implementations' handling of embedded Pod is still a bit uneven; this avoids potential runtime impacts.
  3. A separate repo in the Raku Github account invites more potential contributors and editors.

Q: Should I include methods from superclasses or roles?
A: No. The HTML version already includes methods from superclasses and roles, and the p6doc script will be taught about those as well.


Vision

I want p6doc and docs.raku.org to become the No. 1 resource to consult when you want to know something about a Raku feature, be it from the language, or built-in types and routines. I want it to be useful to every Raku programmer.

-- moritz


ENV VARS

  • P6_DOC_TEST_VERBOSE to a true value to display verbose messages during test suite run. Helpful when debugging failing test suite.
  • P6_DOC_TEST_FUDGE fudges skip-test code examples as TODO in xt/examples-compilation.t test.

UPDATES

Updates are done for the time being by hand. This probably needs improvement.

LICENSE

The code in this repository is available under the Artistic License 2.0 as published by The Perl Foundation. See the LICENSE file for the full text.

This repository also contains code authored by third parties that may be licensed under a different license. Such files indicate the copyright and license terms at the top of the file. Currently these include:

You can’t perform that action at this time.