Merge remote-tracking branch 'upstream/master'

Author: titsuki

.gitignore

@@ -24,4 +24,3 @@ xt/aspell.pws
 highlights/node_modules
 **/npm-debug.log
 highlights/atom-language-perl6/
-examples/

.travis.yml

@@ -1,6 +1,12 @@
 os:
     - linux
-    - osx
+#    - osx
+cache:
+    directories:
+        - precompiled
+        - html
+        - highlights/node_modules
+        - $HOME/.rakudobrew
 addons:
   apt:
     sources:
@@ -10,6 +16,8 @@ addons:
       - g++-4.8
       - ruby-sass
 
+fast_finish: true
+
 branches:
   except:
     - gh-pages
@@ -35,13 +43,13 @@ install:
   - export PATH="$PATH:/$HOME/.rakudobrew/moar-nom/install/share/perl6/site/bin"
   - travis_retry zef --/tap-harness --force --/test install LWP::Simple
   - travis_retry zef --/tap-harness --depsonly install .
-  - travis_retry zef --/tap-harness install Pod::To::HTML
 
 script:
   - make test
   - export CXX=$(command -v g++-4.8 >/dev/null 2>&1; if [ $? -eq 1 ]; then printf "g++"; else printf "g++-4.8"; fi)
   - $CXX --version
-  - make html
+  - make html-nohighlight
+#  - make html
 matrix:
   allow_failures:
     - os: osx

Build.pm

@@ -7,7 +7,7 @@ use File::Find;
 class Build {
     method build($workdir) {
         my $doc-dir   = $workdir.IO.child('doc');
-        my $dest-pref = $*REPO.repo-chain.first(*.?can-install).prefix.child("doc");
+        my $dest-pref = $*REPO.repo-chain.grep(/site/).first.prefix.child("doc");
         mkdir($dest-pref) unless $dest-pref.d;
 
         my @files = find(dir => "$workdir/doc", type => 'file').list;

CONTRIBUTING.md

@@ -15,24 +15,20 @@ in the [#perl6 IRC channel](https://perl6.org/community/irc).
 # TABLE OF CONTENTS
 - [General principles](#general-principles)
 - [Documenting types](#documenting-types)
-- [Testing examples](#testing-examples)
-    - [Skipping tests](#skipping-tests)
+- [Writing and Testing Examples](#writing-and-testing-examples)
 - [Debug mode](#debug-mode)
     - [Invisible index anchors](#invisible-index-anchors)
     - [Viewport size](#viewport-size)
     - [Broken links](#broken-links)
     - [Heading numbering](#heading-numbering)
 - [Reporting bugs](#reporting-bugs)
-- [Website Styles](#website-styles)
 - [Building the documentation](#building-the-documentation)
     - [Dependency installation](#dependency-installation)
         - [Rakudo](#rakudo)
         - [Zef](#zef)
         - [Pod::To::HTML](#podtohtml)
         - [Mojolicious / Web Server](#mojolicious--web-server)
         - [SASS compiler](#sass-compiler)
-        - [pygmentize](#pygmentize)
-        - [Inline::Python](#inlinepython)
     - [Build and view the documentation](#build-and-view-the-documentation)
 
 ## General principles
@@ -60,10 +56,10 @@ you want to improve, commit your changes, and create a pull request. Should
 questions come up in the process feel free to ask in
 [#perl6 IRC channel](https://perl6.org/community/irc).
 
-If the documentation for a type does not exist create the skeleton of the doc
+If the documentation for a type does not exist, create the skeleton of the doc
 with the helper tool `util/new-type.p6`. Say you want to create `MyFunnyRole`:
 
-    $ perl6 util/new-type.p6 MyFunnyRole
+    $ perl6 util/new-type.p6 --kind=role MyFunnyRole
 
 Fill the documentation file `doc/Type/MyFunnyRole.pod6` like this:
 
@@ -109,37 +105,16 @@ When providing a code example result or output, use this style:
 
 Any contributions should pass the `make test` target. This insures basic
 integrity of the documentation, and is run automatically by a corresponding
-travis build. Even edits made via the github editor should pass this test.
+travis build. Even edits made via the GitHub editor should pass this test.
 
 The repo should also pass `make xtest` most of the time - this includes
 tests about whitespace and spelling that might be difficult to get right
 on an initial commit, and shouldn't be considered to break the build. If
 you're contributing a patch or pull request, please make sure this passes.
 
-## Testing examples
+## Writing and Testing Examples
 
-To export examples from all .pod6-files use `make extract-examples`. To run
-individual tests pick the right .p6-file from `examples/` as a parameter to
-`perl6`.
-
-### Skipping tests
-
-Some examples fail with compile time exceptions and would interrupt the test
-for a file. Use the pod-config option `skip-test` to skip them.
-
-    =begin code :skip-test
-        your-example-here();
-    =end code
-
-### Catching expected exception
-
-Some tests will throw exceptions that would stop the execution of the extracted
-test file. Use the pod-option `catch-all` to have a default handler installed
-for a single example.
-
-    =begin code :catch-all
-        exception-generator-here();
-    =end code
+See [Writing and Testing Examples](EXAMPLES.md)
 
 ## Testing method completeness
 
@@ -184,6 +159,8 @@ following labels when tagging tickets:
 
 * site   - presentation issue with the website (e.g. invalid HTML)
 * docs   - missing or incorrect documentation (use 'NOTSPECCED' instead, if this is for a feature present in a compiler, but not in the Perl 6 test suite)
+    * new - this is a new doc item that requires fresh text
+    * update - this is an existing doc item that requires some analysis or editing
 * build  - scripts or libraries that generate the site
 * search - the search component, either for items that are on the site but not searchable, or for search functionality)
 
@@ -195,16 +172,6 @@ Contributors may also specify one of the following tags.
 If you would like to contribute documentation or other bug fixes, please use
 github's Pull request feature.
 
-## Website Styles
-
-The `html/css/style.css` file is built from `assets/sass/style.sass`. Please
-don't edit `html/css/style.css` directly, as your changes will be lost
-the next time the SASS file is processed.
-
-[SASS](http://sass-lang.com/) is a superset of CSS, so if you don't know SASS,
-just write in regular CSS. Run `app.pl` to automatically process SASS and copy
-the result over to `html/css/style.css`
-
 ## Building the documentation
 
 Assuming that you have already forked and cloned the
@@ -221,7 +188,11 @@ computer.  To do this you will need:
     app locally to display the docs)
   - [SASS](http://sass-lang.com/) Compiler
   - [highlights](https://github.com/perl6/atom-language-perl6) (optional; requires
-    only `nodejs` and at least GCC-4.8 on Linux to be installed. Running `make` will set everything up for you.)
+    `nodejs`, `npm`, and at least GCC-4.8 on Linux to be installed. Running `make` will set everything up for you.)
+    - Debian instructions:
+      - Get more modern nodejs than in package manager: `curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -`
+      - Run `make init-highlights` to initialize highlights
+      - If that still isn't working try running `npm install node-gyp -g` and try running make command again
 
 ### Dependency installation
 
@@ -275,55 +246,6 @@ or the [CSS::Sass Perl 5 module](https://modules.perl6.org/repo/CSS::Sass)
 The SASS files are compiled when you run `make html`, or `make sass`, or
 start the development webserver (`./app-start`).
 
-#### pygmentize
-
-This program adds syntax highlighting to the code examples.  Highlighting of
-Perl 6 code was added in version 2.0, so you need at least this version if
-you wish to produced syntax highlighted documentation on your local
-computer.
-
-If you use Debian/Jessie, you can install `pygmentize` via the
-`python-pygments` package:
-
-    $ aptitude install python-pygments
-
-On Ubuntu install the package `python-pygments`:
-
-    $ sudo apt-get install python-pygments
-
-On Fedora the package is also named `python-pygments`:
-
-    $ sudo yum install python-pygments
-
-Otherwise, you probably need to use [`pip`](https://pip.pypa.io/en/latest/)
-(the Python package installer):
-
-    $ pip install pygmentize
-
-#### Inline::Python
-
-`Inline::Python` is optional, however will speed up documentation builds
-using syntax highlighting.
-
-First, you'll need the Python Devel header files and libraries if they have not
-already been installed:
-
-On Debian, install the `python-dev` package:
-
-    aptitude install python-dev
-
-On Ubuntu, the package is also named `python-dev`:
-
-    sudo apt-get install python-dev
-
-On Fedora, install the `python-devel` package:
-
-    sudo yum install python-devel
-
-Use `zef` to install the `Inline::Python` module:
-
-    $ zef install Inline::Python
-
 ### Build and view the documentation
 
 To actually build the documentation all you now need to do is run

CREDITS

@@ -149,6 +149,9 @@ E: justin@devuyst.com
 N: Kamil Kułaga
 E: teodozjan@gmail.com
 
+N: Karl Yerkes
+E: karl.yerkes@gmail.com
+
 N: Klaus Brüssel
 E: trixium@web.de
 
@@ -301,8 +304,8 @@ E: email@froggs.de
 N: Tokuhiro Matsuno
 E: tokuhirom@gmail.com
 
-N: u0097636@kuleuven.be
-E: claudio.ramirez@kuleuven.be
+N: Claudio Ramirez
+E: pub.claudio@gmail.com
 
 N: ugexe
 E: nlogan@gmail.com

EXAMPLES.md

@@ -0,0 +1,84 @@
+## Writing Examples
+
+Please use code blocks to highlight example code; any indented blocks
+are considered to be code, but you can use the `=for code` directive, or a
+combination of `=begin code` and `=end code` to better control which
+blocks are considered.
+
+## Testing Examples
+
+The file `xt/examples-compilation.t` will test the code from all the
+examples. This file is run as part of `make xtest`.
+
+Note that method signatures are also compiled. They have an implied block
+added to insure valid compilation.
+
+Care is taken to wrap the sample code in enough boilerplate so that no
+runtime code is executed, and that a class is available if needed.
+
+## Skipping or finessing tests
+
+While our goal is to test every example of Perl 6 in the repository, some
+blocks are not easy to test. Here are some ways you can skip the test or
+finesse it.
+
+### Other languages
+
+We're just testing Perl 6 here: to skip another language, use `:lang`
+
+    =begin code :lang<tcl>
+        puts "this is not Perl"
+    =end code
+
+### Allow .WHAT
+
+One of the checks is to dissuade using `.WHAT` in tests; However, in rare
+cases that is the explicit point of the test, so you can explicitly allow it:
+
+    =begin code :ok-test<WHAT>
+        say 42.WHAT;
+    =end
+
+### Methods
+
+If a code snippet looks like a method declaration, it's automatically
+wrapped in additional code so you don't have to specify a body in the docs.
+Multi-line method signatures are much harder to detect, so if you have a
+method body that spans likes, use the `:method` tag:
+
+    =begin code :method
+        method arg (
+            Bool $one,
+            Bool $two
+        )
+    =end code
+
+This helps keep the method detection logic in the test code simple.
+
+Conversely, sometimes the method detection is overeager; you can disable it
+entirely with `:method<False>`
+
+### Preambles
+
+When writing examples, it's often helpful to refer to things that aren't
+defined in that snippet; you don't want to have to have a full working
+example in the code.
+
+    =begin code :preamble<no strict;>
+        $x = pi;
+    =end code
+
+    =begin code :preamble<my $x; sub frob {...};>
+        $x = frob();
+    =end code
+
+### Failures
+
+Some examples fail with compile time exceptions and would interrupt the test
+for a file. Use the pod-config option `skip-test` to skip them. When possible,
+specify a reason why you have to use this; it should be considered a last
+resort, and many examples might be amenable to using one of the previous annotations.
+
+    =begin code :skip-test<compile time error>
+        if 1 "missing a block";
+    =end code