diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..94143827 --- /dev/null +++ b/.dockerignore @@ -0,0 +1 @@ +Dockerfile diff --git a/.gitignore b/.gitignore index 2535ee2a..589d00dc 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,6 @@ pkg/ .bundle Gemfile.lock -vendor/ .project .buildpath +*~ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..1875291b --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "vendor/Pod-To-HTML"] + path = vendor/Pod-To-HTML + url = https://github.com/perl6/Pod-To-HTML diff --git a/.travis.yml b/.travis.yml index f118d5cc..e409f596 100644 --- a/.travis.yml +++ b/.travis.yml @@ -14,8 +14,11 @@ notifications: git: depth: 10 before_install: + - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61 + - echo "deb https://dl.bintray.com/nxadm/rakudo-pkg-debs `lsb_release -cs` main" | sudo tee -a /etc/apt/sources.list.d/rakudo-pkg.list - sudo apt-get update -qq - - sudo apt-get install perl + - sudo apt-get install perl rakudo-pkg + - export PATH=$PATH:/.perl6/bin:/opt/rakudo-pkg/bin && install-zef-as-user && zef install Pod::To::HTML - curl -L http://cpanmin.us | perl - --sudo App::cpanminus - sudo cpanm --installdeps --notest Pod::Simple - sudo pip install docutils diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..aa0f09aa --- /dev/null +++ b/Dockerfile @@ -0,0 +1,39 @@ +FROM ubuntu:trusty + +RUN apt-get update -qq +RUN apt-get install -y apt-transport-https + +RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61 +RUN echo "deb https://dl.bintray.com/nxadm/rakudo-pkg-debs `lsb_release -cs` main" | tee -a /etc/apt/sources.list.d/rakudo-pkg.list +RUN apt-get update -qq + +RUN apt-get install -y \ + perl rakudo-pkg curl git build-essential python python-pip \ + libssl-dev libreadline-dev zlib1g-dev \ + libicu-dev cmake pkg-config + +ENV PATH $PATH:/opt/rakudo-pkg/bin +RUN install-zef-as-user && zef install Pod::To::HTML + +RUN curl -L http://cpanmin.us | perl - App::cpanminus +RUN cpanm --installdeps --notest Pod::Simple + +RUN pip install docutils + +ENV PATH $PATH:/root/.rbenv/bin:/root/.rbenv/shims +RUN curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer | bash +RUN rbenv install 2.4.1 +RUN rbenv global 2.4.1 +RUN rbenv rehash + +RUN gem install bundler + +WORKDIR /data/github-markup +COPY github-markup.gemspec . +COPY Gemfile . +COPY Gemfile.lock . +COPY lib/github-markup.rb lib/github-markup.rb +RUN bundle + +ENV LC_ALL en_US.UTF-8 +RUN locale-gen en_US.UTF-8 diff --git a/README.md b/README.md index be9ef8d1..0651c33c 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,8 @@ you wish to run the library. You can also run `script/bootstrap` to fetch them a * [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org) * [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::XHTML` comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN. - +* [.pod6](https://docs.perl6.org/language/pod) -- No additional + dependency beyond perl6 `Pod::To::HTML` (in stdlib) Installation ----------- @@ -38,6 +39,14 @@ Installation gem install github-markup ``` +or + +``` +bundle install +``` + +from this directory. + Usage ----- diff --git a/github-markup.gemspec b/github-markup.gemspec index 7c663d09..2459b753 100644 --- a/github-markup.gemspec +++ b/github-markup.gemspec @@ -12,6 +12,7 @@ Gem::Specification.new do |s| s.license = "MIT" s.files = `git ls-files`.split($\) + s.files += Dir['vendor/Pod-To-HTML/**/*'] s.executables = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) } s.test_files = s.files.grep(%r{^(test|spec|features)/}) s.require_paths = %w[lib] @@ -23,5 +24,5 @@ Gem::Specification.new do |s| s.add_development_dependency 'sanitize', '~> 2.1', '>= 2.1.0' s.add_development_dependency 'nokogiri', '~> 1.8.1' s.add_development_dependency 'nokogiri-diff', '~> 0.2.0' - s.add_development_dependency "github-linguist", "~> 6.0" + s.add_development_dependency "github-linguist", ">= 7.1.3" end diff --git a/lib/github/commands/pod62html b/lib/github/commands/pod62html new file mode 100755 index 00000000..e9e5316a --- /dev/null +++ b/lib/github/commands/pod62html @@ -0,0 +1,10 @@ +#!/usr/bin/env perl6 + +use v6; +use lib $*PROGRAM.IO.parent.add: '../../../vendor/Pod-To-HTML'; +use Pod::To::HTML; + +$_ = Pod::To::HTML.render(slurp); +s:s{\<\!doctype html\>.*\
\<\/div\>\s*} = ""; +s:s{\s*\<\/div\>\s*\<\/body\>\s*\<\/html\>\s*} = ""; +.put; diff --git a/lib/github/markup.rb b/lib/github/markup.rb index 5a78d006..444907a3 100644 --- a/lib/github/markup.rb +++ b/lib/github/markup.rb @@ -19,6 +19,7 @@ module Markups MARKUP_RDOC = :rdoc MARKUP_RST = :rst MARKUP_TEXTILE = :textile + MARKUP_POD6 = :pod6 end module Markup diff --git a/lib/github/markup/implementation.rb b/lib/github/markup/implementation.rb index f2854e22..458ab0d8 100644 --- a/lib/github/markup/implementation.rb +++ b/lib/github/markup/implementation.rb @@ -8,7 +8,11 @@ def initialize(regexp, languages) @regexp = regexp if defined?(::Linguist) - @languages = languages.map {|l| Linguist::Language[l]} + @languages = languages.map do |l| + lang = Linguist::Language[l] + raise "no match for language #{l.inspect}" if lang.nil? + lang + end end end diff --git a/lib/github/markups.rb b/lib/github/markups.rb index 440e0dbf..c900594d 100644 --- a/lib/github/markups.rb +++ b/lib/github/markups.rb @@ -51,4 +51,5 @@ "restructuredtext" ) +command(::GitHub::Markups::MARKUP_POD6, :pod62html, /pod6/, ["Pod 6"], "pod6") command(::GitHub::Markups::MARKUP_POD, :pod2html, /pod/, ["Pod"], "pod") diff --git a/test/markup_test.rb b/test/markup_test.rb index eedaccdf..86c83ee7 100644 --- a/test/markup_test.rb +++ b/test/markup_test.rb @@ -52,7 +52,6 @@ def call define_method "test_#{markup}" do skip "Skipping MediaWiki test because wikicloth is currently not compatible with JRuby." if markup == "mediawiki" && RUBY_PLATFORM == "java" - source = File.read(readme) expected_file = "#{readme}.html" expected = File.read(expected_file).rstrip @@ -67,7 +66,6 @@ def call f.close_write f.read end - assert_html_equal expected, actual, <Title').name assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc', '== Title').name assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst', 'Title').name - assert_equal "pod", GitHub::Markup.renderer('README.pod', '=begin').name + assert_equal "pod", GitHub::Markup.renderer('README.pod', '=head1').name + assert_equal "pod6", GitHub::Markup.renderer('README.pod6', '=begin pod').name end def test_rendering_by_symbol diff --git a/test/markups/README.pod6 b/test/markups/README.pod6 new file mode 100644 index 00000000..c780c5be --- /dev/null +++ b/test/markups/README.pod6 @@ -0,0 +1,151 @@ +=begin pod + +=TITLE About the Docs + +=SUBTITLE Meta-documentation + +This document collection represents the on-going effort to document the Perl 6 programming +language with the goals of being: comprehensive; easy to use; easy to +navigate; and useful to both newcomers and experienced Perl 6 +programmers. + +An HTML version of the documentation is located online at +L. + +The official source for this documentation is located at L. + +This particular document is a quick overview of the process +described in more detail in L. +This document also provides a short introduction to writing Perl 6 +Pod files, which can be rendered into HTML and other formats. + +=head1 Structure + +All of the documentation is written in Perl 6 Pod and kept in the C +directory, and the C and C sub-directories. +These files are processed as collections of definitions or +"documentables", which are then post-processed and linked together. + +=head1 Generating HTML from Pod + +To generate HTML from the Pod files, you'll need: + +=item A recent version of the Rakudo Perl 6 compiler + +=item The Perl 6 modules Pod::To::HTML, Pod::To::BigPage, and URI::Escape +(can be installed via L). + +=item B: L, for creating graphs +of the relationships between Perl 6 types + +=item B: L and L, for syntax +highlighting + +To generate the documentation into the C folder, run: + +=begin code :lang +perl6 htmlify.p6 +=end code + +To host the documentation from a web server, have Perl 5 +and Mojolicious::Lite installed, then run: + +=begin code :lang +perl app.pl daemon +=end code + +=head1 Contributing + +The documentation is written in Perl 6 Pod. + +For a quick introduction to Perl 6 Pod, see L. + +For full details about the Perl 6 Pod specification, see L. + +=head2 Adding definitions + +Documentables can be defined using an C<=headN> Pod directive, where +C is greater than zero (e.g., C<=head1>, C<=head2>, …). + +All of the paragraphs and blocks following that directive, up until the +next directive of the same level, will be considered part of the +documentable. So, in: + +=begin code :allow :skip-test +=head2 R + +Some paragraphs, followed by some code: + + my Code $examples = "amazing"; + +Mind === blown. + +=head3 Minor details about R + +It's fantastic. + +=head2 And now, for something completely different + +… + +=end code + +The documentable R extends down to the C<=head2 And now…>. + +Documentables may contain other documentables. Class documentables, for +example, often contain the methods the class implements. + +Definitions must be in one of the following forms to be recognized as +the start of a documentable named, say, þ. First the code in the document source: + +=begin code :skip-test + +=item X | infix,þ> (This a special case, which +is always considered a definition) + +=item C + +=item B Infix> + +=item C + +=item B> + +=item C (A special case for the L documentables) + +=end code + +Then the results on the rendered page: + +=item X | infix,þ> (This is a special case, which +is always considered a definition) + +=item C + +=item B Infix> + +=item C + +=item B> + +=item C (A special case for the L documentables) + +These items should now be searchable by using the search field in the HTML docs. + +You can add emphasis with bold (B >>) or italicized (B >>), +with or without code formatting (B >>). Due to current parser limitations, +special steps have to be taken to use B >> with other formatting codes; for example: + +=begin code :skip-test +=item X|foo> a fancy subroutine +=end code + +renders like this + +=item X|foo> a fancy subroutine + +Notice that text after a pipe ('|') has no formatting. Also note that B >> +preserves spaces and treats text as verbatim. +=end pod + diff --git a/test/markups/README.pod6.html b/test/markups/README.pod6.html new file mode 100644 index 00000000..3b55d843 --- /dev/null +++ b/test/markups/README.pod6.html @@ -0,0 +1,128 @@ +

About the Docs

+

Meta-documentation

+ + +

Table of Contents

+ + + + + + + + + + + + + + + + + +
1Structure
2Generating HTML from Pod
3Contributing
3.1Adding definitions
+ + +
+

This document collection represents the on-going effort to document the Perl 6 programming language with the goals of being: comprehensive; easy to use; easy to navigate; and useful to both newcomers and experienced Perl 6 programmers.

+

An HTML version of the documentation is located online at https://docs.perl6.org.

+

The official source for this documentation is located at perl6/doc on GitHub.

+

This particular document is a quick overview of the process described in more detail in CONTRIBUTING on GitHub. This document also provides a short introduction to writing Perl 6 Pod files, which can be rendered into HTML and other formats.

+

Structure

+

All of the documentation is written in Perl 6 Pod and kept in the doc/ directory, and the doc/Language/ and doc/Type/ sub-directories. These files are processed as collections of definitions or "documentables", which are then post-processed and linked together.

+

Generating HTML from Pod

+

To generate HTML from the Pod files, you'll need:

+
    +
  • +

    A recent version of the Rakudo Perl 6 compiler

    +
    • +
  • +

    The Perl 6 modules Pod::To::HTML, Pod::To::BigPage, and URI::Escape (can be installed via zef).

    +
    • +
  • +

    Optional: GraphViz, for creating graphs of the relationships between Perl 6 types

    +
    • +
  • +

    Optional: Atom Highlights and language-perl6, for syntax highlighting

    +
    • +
+

To generate the documentation into the html/ folder, run:

+
perl6 htmlify.p6
+
+

To host the documentation from a web server, have Perl 5 and Mojolicious::Lite installed, then run:

+
perl app.pl daemon
+
+

Contributing

+

The documentation is written in Perl 6 Pod.

+

For a quick introduction to Perl 6 Pod, see Perl 6 Pod.

+

For full details about the Perl 6 Pod specification, see Synopsis 26, Documentation.

+

Adding definitions

+

Documentables can be defined using an =headN Pod directive, where N is greater than zero (e.g., =head1, =head2, …).

+

All of the paragraphs and blocks following that directive, up until the next directive of the same level, will be considered part of the documentable. So, in:

+
=head2 My Definition
+
+Some paragraphs, followed by some code:
+
+    my Code $examples = "amazing";
+
+Mind === blown.
+
+=head3 Minor details about My Definition
+
+It's fantastic.
+
+=head2 And now, for something completely different
+
+…
+
+
+

The documentable My Definition extends down to the =head2 And now….

+

Documentables may contain other documentables. Class documentables, for example, often contain the methods the class implements.

+

Definitions must be in one of the following forms to be recognized as the start of a documentable named, say, þ. First the code in the document source:

+
=item X<C<How to use the þ infix> | infix,þ> (This a special case, which
+is always considered a definition)
+
+=item C<The þ Infix>
+
+=item B<The C<þ> Infix>
+
+=item C<Infix þ>
+
+=item B<Infix C<þ>>
+
+=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
+
+
+

Then the results on the rendered page:

+
    +
  • +

    How to use the þ infix (This is a special case, which is always considered a definition)

    +
    • +
  • +

    The þ Infix

    +
    • +
  • +

    The þ Infix

    +
    • +
  • +

    Infix þ

    +
    • +
  • +

    Infix þ

    +
    • +
  • +

    trait is cached (A special case for the trait documentables)

    +
    • +
+

These items should now be searchable by using the search field in the HTML docs.

+

You can add emphasis with bold ( B<> ) or italicized ( I<> ), with or without code formatting ( C<> ). Due to current parser limitations, special steps have to be taken to use X<> with other formatting codes; for example:

+
=item X<B<foo>|foo> a fancy subroutine
+
+

renders like this

+
    +
  • +

    foo a fancy subroutine

    +
    • +
+

Notice that text after a pipe ('|') has no formatting. Also note that C<> preserves spaces and treats text as verbatim.

+
\ No newline at end of file diff --git a/vendor/Pod-To-HTML b/vendor/Pod-To-HTML new file mode 160000 index 00000000..f5ea68c2 --- /dev/null +++ b/vendor/Pod-To-HTML @@ -0,0 +1 @@ +Subproject commit f5ea68c2bb2145dc79f26bf1d9489acb36c0461c