🦋 Perl 6 documentation (tools and docs)
Clone or download
JJ Improves documentation and examples for Mix
The example for the second case was reproduced over and over, but it
didn't behave the same in the first example, so I have changed it to a
new one and explains behavior. Also adds another example for `is`,
which uses a different mechanism, `STORE`

Closes #2459
Latest commit ff2e2bc Nov 15, 2018
Permalink
Failed to load latest commit information.
.github whitespace, also rename .pm to .pm6 Jul 12, 2018
assets Formatting for headers level 4 Oct 9, 2018
bin Eliminates whitespace again Jun 7, 2018
doc Improves documentation and examples for Mix Nov 15, 2018
highlights Address warnings about the package.json file Apr 8, 2018
html Changes encoding Jun 5, 2018
lib categories on language page Oct 8, 2018
resources/i18n whitespace Sep 11, 2018
t Refactor code, add test Jul 7, 2018
template change wording of no-results message to match the new site-search men… Jul 13, 2018
util whitespace Nov 4, 2018
writing-docs Some corrections for next Squashathon Oct 31, 2018
xt Descend into pod items that can contain code Nov 2, 2018
.dockerignore Modified Dockerfile for building/hosting docs Oct 29, 2017
.gitignore resolved links issue Oct 8, 2018
.travis.yml remove trailing whitespace Apr 16, 2018
Build.pm6 pm → pm6 Jul 20, 2018
CONTRIBUTING.md Adds back regexes-best-practices closes #2433 Nov 3, 2018
CREDITS Example use of whenever should use a react block Nov 5, 2018
Dockerfile Correct and clarify some parts of ruby-to-perl6 nutshell. Jul 13, 2018
LICENSE No more trailing whitespace (EVERYWHERE!) May 20, 2016
META6.json Eliminates tabs Oct 16, 2018
Makefile Switching categories back on Nov 2, 2018
README.md We switched to .pod6 a long time ago Oct 15, 2018
app-start Make dev app watch for changes in search.js Apr 27, 2018
app.pl Adds comment to explain behavior, closes #2203 Jul 25, 2018
cpanfile Implement assets generator Apr 2, 2018
htmlify.p6 remove extraneous # Oct 10, 2018
shippable.yml Uses ubuntu package Apr 22, 2018
type-graph.txt utf8 added to type graph Oct 25, 2018

README.md

Official Documentation of Perl 6

Build Status artistic

Run Status

An HTML version of this documentation can be found at https://docs.perl6.org/. 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).

README in other languages

Install p6doc

This module is available via the Perl 6 module ecosystem. Use:

$ zef install p6doc

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

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

Use p6doc

With a Rakudo perl6 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. Depending on your disk speed and Rakudo version, it might take a while.


Building the HTML documentation

Install dependencies by running the following in the checkout directory:

$ zef --deps-only install .

If you use rakudobrew, also run the following, to update the shims for installed executables:

$ rakudobrew rehash

In addition to the Perl 6 dependencies, you need to have graphviz installed, which on Debian you can do by running:

$ sudo apt-get install graphviz

To build the documentation web pages, simply run:

$ make html

Please note that you will need to have nodejs installed to produce HTML content with the above command, in particular a node executable should be in your PATH. Besides, you will need to have g++ installed in order to build some of the dependencies that are installed with nodejs. nodejs is needed only to apply highlighting to the included code; if you do not want that, simply write

$ make html-nohighlight

After the pages have been generated, you can view them on your local computer by starting the included app.pl program:

$ make run

You can then view the examples documentation by pointing your web browser at http://localhost:3000.

You will need at least Mojolicious installed and you will need nodejs to perform highlighting. There are also some additional modules you might need; install them all using:

$ cpanm --installdeps .

Help Wanted!

Perl 6 is not a small language, and documenting it 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 Perl 6 implementation.
  2. Implementations' handling of embedded Pod is still a bit uneven; this avoids potential runtime impacts.
  3. A separate repo in the perl6 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.perl6.org to become the No. 1 resource to consult when you want to know something about a Perl 6 feature, be it from the language, or built-in types and routines. I want it to be useful to every Perl 6 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.

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: