Merge pull request #1 from Raku/master

merge upstream

Author: finanalyst

.github/ISSUE_TEMPLATE/bug-report-or-feature-request.md

@@ -0,0 +1,16 @@
+---
+name: Bug report or feature request
+about: Create a report to help us improve
+title: ''
+labels: docs
+assignees: ''
+
+---
+
+## Problem or new feature
+
+A clear and concise description of what the bug is, including links to the page where you have found it.
+
+## Suggestions
+
+If applicable, suggest something towards the solution.

.github/issue_template.md

@@ -33,3 +33,4 @@ node_modules/
 package-lock.json
 *.epub
 .idea
+*.iml

.gitignore

@@ -1,6 +1,6 @@
 # Contributing
 
-Your patches to `perl6/doc` are very welcome, and if you want to
+Your patches to `Raku/doc` are very welcome, and if you want to
 help,
 [please read this guide](https://dev.to/jj/squashing-perl-6-documentation-bugs-one-at-a-time-4ojn) as
 well as the detailed instructions below.
@@ -28,6 +28,7 @@ in the [#raku IRC channel](https://raku.org/community/irc).
     - [Broken links](#broken-links)
     - [Heading numbering](#heading-numbering)
 - [Reporting bugs](#reporting-bugs)
+- [Contributing pull requests](#contributing-pull-requests)
 - [Building the documentation](#building-the-documentation)
     - [Dependency installation](#dependency-installation)
         - [Rakudo](#rakudo)
@@ -68,7 +69,7 @@ available when writing code examples in the documentation.
 ## Adding a new Language document
 
 We suggest you discuss proposing a new Language document on the #raku
-channel and/or the [issues for this repository](https://github.com/perl6/doc/issues)
+channel and/or the [issues for this repository](https://github.com/Raku/doc/issues)
 before you proceed further. After you get consensus on a title, subtitle,
 section, and filename, you can add the document by following these steps:
 
@@ -82,8 +83,8 @@ section, and filename, you can add the document by following these steps:
 
 ## Documenting types
 
-The Pod 6 documentation of types is located in the `doc/Type` directory and
-subdirectories of this repository. For example the Pod 6 file of `X::Bind::Slice`
+The Pod6 documentation of types is located in the `doc/Type` directory and
+subdirectories of this repository. For example the Pod6 file of `X::Bind::Slice`
 lives in `doc/Type/X/Bind/Slice.pod6`.
 
 To start contributing, fork and checkout the repository, find the document
@@ -162,9 +163,9 @@ See [Writing and Testing Examples](writing-docs/EXAMPLES.md)
 ## Testing method completeness
 
 To get a list of methods that are found via introspection but not found in any
-Pod 6 file under `doc/Type/`, use `util/list-missing-methods.p6`. It takes a
+Pod6 file under `doc/Type/`, use `util/list-missing-methods.p6`. It takes a
 directory or filepath as argument and limits the listing to the given file or
-any Pod 6-files found. All methods listed in `util/ignored-methods.txt` are
+any Pod6 files found. All methods listed in `util/ignored-methods.txt` are
 ignored.
 
 ## Debug mode
@@ -192,36 +193,39 @@ to display heading numbers.
 
 ## Reporting bugs
 
-Report issues at https://github.com/perl6/doc/issues. You can
+Report issues at https://github.com/Raku/doc/issues. You can
 use
-[labels when tagging tickets](https://github.com/perl6/doc/labels),
+[labels when tagging tickets](https://github.com/Raku/doc/labels),
 among which these are probably the most common:
 
-* [`docs`](https://github.com/perl6/doc/labels/docs)   - missing or
+* [`docs`](https://github.com/Raku/doc/labels/docs)   - missing or
   incorrect documentation;
-  use [`NOTSPECCED`](https://github.com/perl6/doc/labels/NOTSPECCED)
+  use [`NOTSPECCED`](https://github.com/Raku/doc/labels/NOTSPECCED)
   instead, if this is for a feature present in a compiler, but not in
   the Raku test suite.
-* [`search`](https://github.com/perl6/doc/labels/search) - the search
+* [`search`](https://github.com/Raku/doc/labels/search) - the search
   component, either for items that are on the site but not searchable,
   or for the search functionality itself.
 
+## Contributing pull requests
+
 If you would like to contribute documentation or other bug fixes, please use
-[GitHub's pull requests](https://github.com/perl6/doc/pulls).
+[GitHub's pull requests (PRs)](https://github.com/Raku/doc/pulls). For a complete
+recipe for a new PR contributor, check [this PR guide](https://github.com/tbrowder/tidbits/blob/master/Contributing-PRs.md).
 
 ## Building the documentation
 
 Assuming that you have already forked and cloned the
-[perl6/doc](https://github.com/perl6/doc) repository, one of the first things
+[Raku/doc](https://github.com/Raku/doc) repository, one of the first things
 you probably want to do is to build the documentation on your local
 computer. To do this you will need:
 
   - Raku (e.g., the Rakudo Raku implementation)
   - zef (the installer for third party Raku modules)
-  - `Pod::To::HTML` (Raku module for converting Pod 6 objects to HTML)
+  - `Pod::To::HTML` (Raku module for converting Pod6 objects to HTML)
   - [graphviz](http://www.graphviz.org/) (`sudo apt-get install graphviz` on Debian/Ubuntu)
   - [Mojolicious](https://metacpan.org/pod/Mojolicious)
-    (optional; a Perl 5 web framework; it allows you to run a web
+    (optional; a Perl web framework; it allows you to run a web
     app locally to display the docs)
   - [SASS](http://sass-lang.com/) Compiler
   - [highlights](https://github.com/perl6/atom-language-perl6) (optional; requires
@@ -250,7 +254,7 @@ use any other module installer for the modules needed (see below).
 #### Building the documentation
 
 The program that builds the HTML version of the documentation
-(`htmlify.p6`) uses `Pod::To::HTML` to convert Pod 6 structures into HTML.
+(`htmlify.p6`) uses `Pod::To::HTML` to convert Pod6 structures into HTML.
 You'll also need `Pod::To::BigPage` and `Perl6::TypeGraph`. Install these modules like so:
 
     $ zef install Pod::To::HTML Pod::To::BigPage Perl6::TypeGraph
@@ -263,15 +267,15 @@ you're good to go.
 
 #### Mojolicious / Web Server
 
-This is a Perl 5 web framework which is used to run the included
+This is a Perl web framework which is used to run the included
 web application that displays the HTML documentation in a web browser. It's
 no required for development, as the site is static and you can serve it using
 any other webserver.
 
 The app *does* automatically convert the SASS file to CSS, so it's handy to
 use for that as well.
 
-Mojolicious is written in Perl 5, so assuming that you use
+Mojolicious is written in Perl, so assuming that you use
 [`cpanm`](https://metacpan.org/pod/App::cpanminus),
 install this now:
 
@@ -284,7 +288,7 @@ the `sass` command
 
     $ sudo apt-get install ruby-sass
 
-or the [CSS::Sass Perl 5 module](https://modules.raku.org/repo/CSS::Sass)
+or the [CSS::Sass Perl module](https://modules.raku.org/repo/CSS::Sass)
 
     $ cpanm -vn CSS::Sass Mojolicious::Plugin::AssetPack
 
@@ -318,12 +322,12 @@ 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`:/perl6/doc perl6-doc
+    $ docker run -p 3000:3000 -it -v `pwd`:/Raku/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`:/perl6/doc perl6-doc ./app-start
+    $ docker run -p 3000:3000 -it -v `pwd`:/Raku/doc perl6-doc ./app-start
 
 Now point your web browser to http://localhost:3000 to view the documentation.
 

CONTRIBUTING.md

@@ -11,7 +11,7 @@
 
         Thanks,
 
-        The perl6/doc Team
+        The Raku/doc Team
         PS: Yes, this looks remarkably like the Linux CREDITS format
         PPS: This file is encoded in UTF-8
 

CREDITS

@@ -24,7 +24,7 @@ RUN buildDeps='         \
     && chmod +x "$n"      \
     && n stable
 
-WORKDIR /perl6/doc
+WORKDIR /Raku/doc
 COPY . .
 RUN zef install zef && zef update && zef install --deps-only .
 

Dockerfile

@@ -13,6 +13,7 @@
     "JSON::Fast",
     "Pod::To::BigPage:ver<0.5.1+>",
     "Pod::To::HTML:ver<0.6.1+>",
+    "Pod::Utilities",
     "OO::Monitors",
     "File::Find",
     "Test::META",
@@ -28,7 +29,7 @@
     "Test-Files": "lib/Test-Files.pm6"
   },
   "support": {
-    "source": "git://github.com/perl6/doc.git"
+    "source": "git://github.com/Raku/doc.git"
   },
   "license": "Artistic-2.0",
   "tags": [
@@ -37,6 +38,6 @@
     "documentation",
     "reference"
   ],
-  "source-url": "git://github.com/perl6/doc.git",
+  "source-url": "git://github.com/Raku/doc.git",
   "meta6": "0"
-}
+}

META6.json

@@ -3,35 +3,31 @@ PATH := $(PATH)
 DOCKER_IMAGE_NAME    ?= p6doc
 DOCKER_HOST_PORT     ?= 3000
 DOCKER_SELINUX_LABEL ?= 0
-COLON_Z              := :Z
-SELINUX_OPT          := $(shell [ $(DOCKER_SELINUX_LABEL) -eq 1 ] && echo "$(COLON_Z)" || echo '' )
-# dependencies for a new doc/Language build:
-LANG_POD6_SOURCE     := $(wildcard doc/Language/*.pod6)
-# Managing of the language index page
-USE_CATEGORIES := True
-
-.PHONY: html init-highlights html-nohighlight sparse assets webdev-build \
-	bigpage test xtest ctest help run clean-html clean-images \
+ifeq ($(DOCKER_SELINUX_LABEL),1)
+SELINUX_OPT          := :Z
+else
+SELINUX_OPT          :=
+endif
+
+.PHONY: html init-highlights assets \
+	test xtest ctest help run clean-html clean-images \
 	clean-search clean test-links push \
-        gen-pod6-source clean-build \
+	clean-cache \
 	docker-image docker-test docker-xtest docker-ctest docker-testall docker-run
 
-html: gen-pod6-source bigpage
+html: for-documentable
+	documentable start -a -v --highlight
 
-init-highlights:
+init-highlights highlights/package-lock.json:
 	ATOMDIR="./highlights/atom-language-perl6";  \
 	if [ -d "$$ATOMDIR" ]; then (cd "$$ATOMDIR" && git pull); \
 	else git clone https://github.com/perl6/atom-language-perl6 "$$ATOMDIR"; \
 	fi; cd highlights; npm install .; npm rebuild
 
-assets:
+assets assets/assetpack.db:
 	./app.pl assets
 
-bigpage: gen-pod6-source
-	pod2onepage --html -v --source-path=./build --exclude=404.pod6 > html/perl6.html
-
-epub: bigpage
-	pandoc html/perl6.html -o perl6.epub
+for-documentable: highlights/package-lock.json assets/assetpack.db
 
 # Common tests that are run by travis with every commit
 test:
@@ -46,15 +42,11 @@ ctest:
 	prove --exec perl6 -r t/07-tabs.t xt/perl-nbsp.t  xt/trailing-whitespace.t
 
 help:
-	@echo "Usage: make [html|html-nohighlight|test|xtest|ctest]"
+	@echo "Usage: make [html|test|xtest|ctest]"
 	@echo ""
 	@echo "Options:"
 	@echo "   html:             generate the HTML documentation"
-	@echo "   html-nohighlight: generate HTML documentation without syntax highlighting"
 	@echo "   assets:           generate CSS/JS assets"
-	@echo " sparse:             generate HTML documentation, but only every 10th file"
-	@echo "webdev-build:        generate only a few HTML files (useful for testing website changes)"
-	@echo "bigpage:             generate HTML documentation in one large file (html/perl6.html)"
 	@echo "init-highlights:     install prereqs for highlights (runs as part of 'make html')"
 	@echo "   test:             run the test suite"
 	@echo "  xtest:             run the test suite, including extra tests"
@@ -78,21 +70,21 @@ docker-image:
 	docker build -t $(DOCKER_IMAGE_NAME) .
 
 docker-test: docker-image
-	docker run --rm -it -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+	docker run --rm -it -v $(REPO_PATH):/Raku/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
 		/bin/bash -c 'make test'
 
 docker-xtest: docker-image
-	docker run --rm -it -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+	docker run --rm -it -v $(REPO_PATH):/Raku/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
 		/bin/bash -c 'make xtest'
 
 docker-ctest: docker-image
-	docker run --rm -it -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) $(DOCKER_IMAGE_NAME) \
+	docker run --rm -it -v $(REPO_PATH):/Raku/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 -it -p $(DOCKER_HOST_PORT):3000 -v $(REPO_PATH):/perl6/doc/$(SELINUX_OPT) \
+	docker run --rm -it -p $(DOCKER_HOST_PORT):3000 -v $(REPO_PATH):/Raku/doc/$(SELINUX_OPT) \
 		$(DOCKER_IMAGE_NAME) /bin/bash -c './app-start' &
 
 clean-html:
@@ -112,15 +104,18 @@ clean-images:
 clean-search:
 	rm -f html/js/search.js
 
-clean-build:
-	find build -name "*.pod6" -exec rm -f {} \;
-
-remove-build:
-	rm -rf build
+clean-cache:
+	-rm -rf .cache-doc
 
-clean: clean-html clean-images clean-search clean-build
+clean: clean-html clean-images clean-search
 
-distclean: clean remove-build
+distclean: clean clean-cache
+	-rm -rf assets/assetpack.db assets/cache
+	-rm -rf highlights/atom-language-perl6/
+	-rm -rf highlights/node_modules/
+	-rm -rf highlights/package-lock.json
+	-rm -rf html/css/app.css
+	-rm -rf html/js
 
 
 test-links: links.txt