代码拉取完成，页面将自动刷新
Your patches to perl6/doc are very welcome.
This document describes how to get started and helps to provide documentation that adheres to the common style and formatting guidelines.
Your contributions will be credited in Rakudo release announcement. You name from the commit log will be used. If you'd like to be credited under a different name, please add it to CREDITS file
If you have any questions regarding contributing to this project, please ask in the #perl6 IRC channel.
*%args,
but treats some of them specially, list them separately.See EXAMPLES.md for detailed information on the options available when writing code examples in the documentation.
The POD documentation of types is located in the doc/Type directory and
subdirectories of this repository. For example the POD of X::Bind::Slice
lives in doc/Type/X/Bind/Slice.pod6.
To start contributing fork and checkout the repository, find the document 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.
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 --kind=role MyFunnyRole
Fill the documentation file doc/Type/MyFunnyRole.pod6 like this:
=TITLE role MyFunnyRole
=SUBTITLE Sentence or half-sentence about what it does
role MyFunnyRole does OtherRole is SuperClass { ... }
Longer description here about what this type is, and
how you can use it.
# usage example goes here
=head1 Methods
=head2 method do-it
method do-it(Int $how-often --> Nil:D)
Method description here
MyFunnyRole.do-it(2); # OUTPUT: «example output»
When documenting a pair of a sub and a method which both do the same thing, the
heading should be =head2 routine do-it, and the next thing should be two or
more lines with the signatures. Other allowed words instead of method are
sub, trait, infix, prefix, postfix, circumfix, postcircumfix,
term. If you wish to hide a heading from any index prefix it with the empty
comment Z<>.
When providing a code example result or output, use this style:
# For the result of an expression.
1 + 2; # RESULT: «3»
# For the output.
say 1 + 3; # OUTPUT: «3»
# For the explanatory comment
do-work; # We call do-work sub
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.
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.
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
See Writing and Testing Examples
To get a list of methods that are found via introspection but not found in any
pod6 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 pod6-files found. All methods listed in util/ignored-methods.txt are
ignored.
On the right side of the footer you can find [Debug: off]. Click it and reload
the page to activate debug mode. The state of debug mode will be remembered by
window.sessionStorage and will not survive a browser restart or opening the
docs in a new tab.
You can create index entries and invisible anchors with X<|thing,category>.
To make them visible activate debug mode.
If you change the layout please check different screen sizes. Debug mode will display the viewport size in the bottom left corner.
To check for broken links use debug mode. Any spotted broken link will be listed under the search input. Please note that some external links may not get checked depending on your browser settings.
Please check if the headings you add are of sound structure. You can use debug mode to display heading numbers.
Report issues at https://github.com/perl6/doc/issues. You can use the following labels when tagging tickets:
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.
Assuming that you have already forked and cloned the perl6/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:
Pod::To::HTML (Perl 6 module for converting Pod objects to HTML)sudo apt-get install graphviz on Debian/Ubuntu)nodejs, npm, and at least GCC-4.8 on Linux to be installed. Running make will set everything up for you.)
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
make init-highlights to initialize highlightsnpm install node-gyp -g and try running make command againYou need Perl 6 installed. You can install the Rakudo Perl 6 compiler by downloading the latest Rakudo Star release from rakudo.org/downloads/star/
Zef is a Perl 6 module installer. If you installed Rakudo Star package, it should already be installed. Feel free to use any other module installer for the modules needed (see below).
The program that builds the HTML version of the documentation
(htmlify.p6) uses Pod::To::HTML to convert Pod structures into HTML.
You'll also need Pod::To::BigPage. Install these modules like so:
$ zef install Pod::To::HTML Pod::To::BigPage
This is a Perl 5 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
cpanm,
install this now:
$ cpanm -vn Mojolicious
To build the styles, you need to have a SASS compiler. You can either install
the sass command
$ sudo apt-get install ruby-sass
or the CSS::Sass Perl 5 module
$ cpanm -vn CSS::Sass Mojolicious::Plugin::AssetPack
The SASS files are compiled when you run make html, or make sass, or
start the development webserver (./app-start).
To actually build the documentation all you now need to do is run
htmlify.p6:
$ perl6 htmlify.p6
This takes a while, but be patient!
After the build has completed, you can start the web application which will render the HTML documentation
$ perl app.pl daemon # note! Perl 5 *not* Perl 6 here
Now point your web browser to http://localhost:3000 to 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.
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。