Merge branch 'master' of https://github.com/perl6/doc

Author: Patrick Sebastian Zimmermann

.dockerignore

@@ -0,0 +1,5 @@
+./*
+.sass-cache/
+.git/
+.gitignore
+.travis.yml

CONTRIBUTING.md

@@ -30,7 +30,7 @@ in the [#perl6 IRC channel](https://perl6.org/community/irc).
         - [Mojolicious / Web Server](#mojolicious--web-server)
         - [SASS compiler](#sass-compiler)
     - [Build and view the documentation](#build-and-view-the-documentation)
-        - [Using Docker](#using-docker)
+        - [Using Docker](#using-docker-to-build-and-view-the-documentation)
 
 ## General principles
 
@@ -113,6 +113,11 @@ 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.
 
+If you have local modifications and want to insure they pass xtest before
+committing, you can use this command to test only modified files:
+
+  TEST_FILES=`git status --porcelain --untracked-files=no | awk '{print $2}'` make xtest
+
 ## Writing and Testing Examples
 
 See [Writing and Testing Examples](EXAMPLES.md)
@@ -264,15 +269,39 @@ render the HTML documentation
 Now point your web browser to http://localhost:3000 to view the
 documentation.
 
-#### Using Docker
+#### Using Docker to build and view the documentation
 
 You can skip all the above and just build and view documentation with these simple commands (if you have docker already installed):
 
     $ docker build -t perl6-doc .
     $ docker run -p 3000:3000 -it -v `pwd`:/doc perl6-doc
 
 This will build the documentation for you by default and it will take some time, but for subsequent use you may want to skip build part if nothing has been changed:
- 
+
     $ docker run -p 3000:3000 -it -v `pwd`:/doc perl6-doc bash -c "perl app.pl daemon"
 
 Now point your web browser to http://localhost:3000 to view the documentation.
+
+Alternatively, you can use make to build and run your container. To build the image:
+
+    $ make docker-image
+
+To build the HTML documentation:
+
+    $ make docker-htmlify
+
+To run the development web server for viewing documentation (on port 3000):
+
+    $ make docker-run
+
+Note that while this requires less typing, some assumptions will be made for you regarding the name
+of the resulting image, the port the content is available over, etc. If you want, you can
+override these default values.
+
+For instance, if you want the local documentation to be available over port 5001 of the host,
+pass the following to make when running:
+
+    $ make docker-run DOCKER_HOST_PORT=5001
+
+Now the documentation will be available on the host at http://localhost:5001. Please see the
+Makefile for a list of available options.

Dockerfile

@@ -1,25 +1,36 @@
 FROM rakudo-star:latest
 
-RUN curl -sL https://deb.nodesource.com/setup_6.x | bash -
-
-RUN apt-get --yes --no-install-recommends install \
-    ruby-sass \
-    cpanminus \
-    build-essential \
-    nodejs \
-    graphviz \
-    ;
-
-RUN zef install Pod::To::HTML Pod::To::BigPage
-
-RUN cpanm -vn Mojolicious
-
-RUN cpanm -vn CSS::Sass Mojolicious::Plugin::AssetPack
-
-RUN mkdir /doc
-
-WORKDIR /doc
-
-EXPOSE 3000
-
-CMD bash -c "make init-highlights && perl6 htmlify.p6 && perl app.pl daemon"
+RUN buildDeps=' \
+        build-essential \
+        cpanminus \
+        npm \
+    ' \
+    runtimeDeps=' \
+        graphviz \
+        make \
+        nodejs \
+        ruby-sass \
+    ' \
+    testDeps=' \
+        aspell \
+    ' \
+
+    && set -x \
+    && apt-get update \
+    && apt-get --yes --no-install-recommends install $buildDeps $runtimeDeps $testDeps \
+    && rm -rf /var/lib/apt/lists/* \
+
+    && cpanm -vn Mojolicious \
+    && zef install Test::META \
+
+    && ln -s /usr/bin/nodejs /usr/bin/node \
+    && npm cache clean -f \
+    && npm install -g n \
+    && n stable \
+
+    && apt-get purge --yes --auto-remove $buildDeps
+
+WORKDIR /perl6/doc/
+EXPOSE  3000
+
+CMD bash -c 'make test && make html && ./app-start'

Makefile

@@ -1,6 +1,14 @@
+REPO_PATH := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+
+DOCKER_IMAGE_NAME    ?= p6doc
+DOCKER_HOST_PORT     ?= 3000
+DOCKER_SELINUX_LABEL ?= 0
+SELINUX_OPT          := $(shell [ $(DOCKER_SELINUX_LABEL) -eq 1 ] && echo ':Z' || echo '' )
+
 .PHONY: html init-highlights html-nohighlight sparse sass webdev-build bigpage \
 	test xtest ctest help run clean-html clean-examples clean-images \
-	clean-search clean test-links extract-examples push
+	clean-search clean test-links extract-examples push \
+	docker-image docker-htmlify docker-test docker-xtest docker-ctest docker-testall docker-run
 
 html: bigpage htmlify
 
@@ -54,11 +62,43 @@ help:
 	@echo "  xtest:             run the test suite, including extra tests"
 	@echo "  ctest:             run the test suite, content tests only"
 	@echo "    run:             run the development webserver"
+	@echo "docker-image:        build Docker image from Dockerfile"
+	@echo "docker-htmlify:      generate the HTML documentation (in container)"
+	@echo "docker-test:         run the test suite (in container)"
+	@echo "docker-xtest:        run the test suite, including extra tests (in container)"
+	@echo "docker-ctest:        run the test suite, content tests only (in container)"
+	@echo "docker-testall:      run all tests (in container)"
+	@echo "docker-run:          run the development webserver (in container)"
 
 run:
 	@echo "Starting local server…"
 	morbo -w assets app.pl
 
+docker-image:
+	docker build -t $(DOCKER_IMAGE_NAME) .
+
+docker-htmlify: docker-image docker-test
+	docker run --rm -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+		/bin/bash -c 'make html'
+
+docker-test: docker-image
+	docker run --rm -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+		/bin/bash -c 'make test'
+
+docker-xtest: docker-image
+	docker run --rm -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+		/bin/bash -c 'make xtest'
+
+docker-ctest: docker-image
+	docker run --rm -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+		/bin/bash -c 'make ctest'
+
+docker-testall: docker-test docker-xtest docker-ctest
+
+docker-run: docker-image
+	docker run --rm -p $(DOCKER_HOST_PORT):3000 -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) \
+		$(DOCKER_IMAGE_NAME) /bin/bash -c './app-start' &
+
 clean-html:
 	rm -rf html/*.html html/.*.html \
 		html/language/ \

doc/Language/grammar_tutorial.pod6

@@ -49,7 +49,7 @@ Grammars are made up of methods that define a regex, a token, or a rule.
 These are all varieties of different types of match methods. Once you have a
 grammar defined, you call it and pass in a string for parsing.
 
-    =begin code :preamble<grammar G{};>
+    =begin code :preamble<grammar G{};my $string;>
     my $matchObject = G.parse($string);
     =end code
 

doc/Language/grammars.pod6

@@ -36,7 +36,7 @@ the C<my> keyword, because named regexes are normally used within grammars.
 Being named gives us the advantage of being able to easily reuse the regex
 elsewhere:
 
-    =begin code :preamble<my regex number{};>
+    =begin code :preamble<my regex number{...};>
     say so "32.51" ~~ &number;                         # OUTPUT: «True␤»
     say so "15 + 4.5" ~~ /<number>\s* '+' \s*<number>/ # OUTPUT: «True␤»
     =end code
@@ -93,7 +93,7 @@ L<action object|/language/grammars#Action_Objects> is recommended to be used in
 conjunction with the grammar.
 
 
-=head2 X<Protoregexes| sym; :sym<>; protoregex>
+=head2 X«Proto regexes| sym; :sym<>; proto regex»
 
 If you have a lot of alternations, it may become difficult to produce
 readable code or subclass your grammar. In the Actions class below, the
@@ -117,7 +117,7 @@ operations we add:
 
     # OUTPUT: «5␤»
 
-To make things better, we can use protoregexes that look like C«:sym<...>»
+To make things better, we can use proto regexes that look like C«:sym<...>»
 adverbs on tokens:
 
     grammar Calculator {
@@ -170,7 +170,7 @@ calculator:
     =end code
 
 All we had to add are additional rule and action to the C<calc-op> group and
-the thing works—all thanks to protoregexes.
+the thing works—all thanks to proto regexes.
 
 =head2 Special Tokens
 
@@ -363,7 +363,8 @@ A slightly more involved example follows:
         }
     }
 
-    my  $res = KeyValuePairs.parse(q:to/EOI/, :actions(KeyValuePairsActions)).made;
+    my $actions = KeyValuePairsActions.new;
+    my $res = KeyValuePairs.parse(q:to/EOI/, :$actions).made;
         second=b
         hits=42
         perl=6
@@ -376,11 +377,11 @@ A slightly more involved example follows:
 
 This produces the following output:
 
-=begin code :lang<text>
-Key: second     Value: b
-Key: hits       Value: 42
-Key: perl       Value: 6
-=end code
+    =begin code :lang<text>
+    Key: second     Value: b
+    Key: hits       Value: 42
+    Key: perl       Value: 6
+    =end code
 
 Rule C<pair>, which parsed a pair separated by an equals sign, aliases the two
 calls to token C<identifier> to separate capture names to make them available

doc/Language/objects.pod6

@@ -712,7 +712,7 @@ This check will save you a lot of headaches:
     =begin code :preamble<role Bull-Like{}; role Steerable{};>
     class Taurus does Bull-Like does Steerable {
         method steer($direction?) {
-            self.Steerable::steer($direction?)
+            self.Steerable::steer($direction)
         }
     }
     =end code