Merge pull request #128 from Raku/develop

Develop, fix #127
Raku · Aug 1, 2020 · 16a2b7c · 16a2b7c
2 parents 9563911 3288ea9
commit 16a2b7c
Show file tree

Hide file tree

Showing 6 changed files with 178 additions and 9 deletions.
diff --git a/META6.json b/META6.json
@@ -1,7  1,7 @@
 {
   "name": "Documentable",
   "description": "An API for Raku documentation",
-  "version": "2.0.0",
   "version": "2.0.1",
   "perl": "6.d",
   "authors": [
     "@moritz",
@@ -14,7  14,7 @@
   "auth": "github:Raku",
   "depends": [
     "Pod::Load:ver<0.5.4>",
-    "Pod::To::HTML:ver<0.7.0>",
     "Pod::To::HTML:ver<0.7.1>",
     "Pod::From::Cache:ver<0.2>",
     "Perl6::TypeGraph:ver<2.1.3>:auth<github:antoniogamiz>:api<2>",
     "Pod::Utilities:ver<0.0.1>",
@@ -25,7  25,7 @@
     "Test::Output",
     "Terminal::ANSIColor",
     "File::Directory::Tree",
-    "Template::Mustache",
     "Template::Mustache:ver<1.2.2 >",
     "node:from<bin>",
     "dot:from<bin>"
   ],

diff --git a/docs/Language/template.pod6 b/docs/Language/template.pod6
@@ -0,0  1,99 @@
 =begin pod :kind("Language") :subkind("Language") :category("setup")
 
 =TITLE Mustache Template
 
 =SUBTITLE Variables used in the default template
 
 C«Documentable» the same L«Mustache|https://mustache.github.io/» template as base
 to generate every HTML page. If do not define your own in C«/template/main.mustache»,
 the L«default one|https://github.com/Raku/Documentable/blob/master/resources/template/main.mustache»
 will be used.
 
 We use L«Pod::To::HTML|https://github.com/Raku/Pod-To-HTML», so check it out to see the variables that have
 not been listed here.
 
 =head1 Variables
 
 Everything between I«{{{}}}» and I«{{}}» is considered a variable and will be replaced by C«Documentable».
 
 =head2 X«{{{title}}}»
 
 It is replaced with the contents of C«=TITLE» element. It will always be replaced because C«Documentable»
 will throw an error if a C«=TITLE» element is not found in all pods (see L«TitleNotFound|/type/X::Documentable::TitleNotFound»).
 
 =head2 X«{{subtitle}}»
 
 It is replaced with the contents of C«=SUBTITLE» element. It will always be replaced because C«Documentable»
 will throw an error if a C«=SUBTITLE» element is not found in all pods (see L«SubtitleNotFound|/type/X::Documentable::SubtitleNotFound»).
 
 =head2 X«{{css}}»
 
 It is replaced with the path to the default CSS file location, C«/css/app.js». If you want to use your
 own CSS file in a different location, delete that variable and replace it with the new path.
 
 =head2 X«{{prefix}}»
 
 It is replaced with the L«url-prefix|/language/configuration-file#Additional_entries»
 entry from the configuration file. This is normally used when you want to publish your site under C«gh-pages» or similar,
 or if you want to publish several versions of your docs.
 
 If you are going to use a hardcoded URL in the template (a static image, for instance), add this variable to the beginning of
 the path, as follows:
 
 =begin code :lang«HTML»
 
  «img src="{{prefix}}/images/Camelia.svg"»«/img»
 
 =end code
 
 =head2 X«{{menu}}»
 
 It is replaced with the menu entries. Each menu entries has three different values:
 
 =item X«{{{class}}}»: replaced by C«"selected darker-green"» if that menu is clicked or C«""» in other case.
 =item X«{{{href}}}»: URL to the index page of that menu.
 =item X«{{{display-text}}}»: Display text of that menu, configured using the L«config file|/language/configuration-file».
 
 =head2 X«{{submenu}}»
 
 It is replaced with the submenu entries. You can create as many of these entries using the C«categories» entry from the
 L«config file|/language/configuration-file». Each menu entries has two different values:
 
 =item X«{{{href}}}»: URL to the index page of that menu.
 =item X«{{{display-text}}}»: Display text of that menu, configured using the L«config file|/language/configuration-file».
 
 =head2 X«{{editable}}»
 
 It is replaced by C«""» in case the HTML page comes from a L«Documentable::Primary|/type/Documentable::Primary» object. In
 any other case, it will be replaced by C«"none"».
 
 =head2 X«{{editURL}}»
 
 It is replaced by the source url of the pod. It only works with GitHub based URLs. It uses L«pod-root-path|/language/configuration-file#Additional_entries»
 to build it.
 
 =head2 X«{{toc}}»
 
 It is replaced with the Table of Contents, if it exists. X«toc-class» is a special string replaced by C«Documentable» with
 
 =begin code :lang«HTML»
 {{^ toc }} no-toc{{/ toc }}
 =end code
 
 This is necessary because to reduce the generation time, C«Documentable» creates as many base templates as possible (replacing some common
 variables for all pages). See L«softmoth/raku-Template-Mustache#36|https://github.com/softmoth/raku-Template-Mustache/issues/36» for more
 information.
 
 =head2 X«{{body}}»
 
 It is replaced by the pod converted to HTML. See L«Pod::To::HTML|https://github.com/Raku/Pod-To-HTML» for more information.
 
 =head2 X«{{footnotes}}»
 
 It is replaced by the footnotes converted to HTML. See L«Pod::To::HTML|https://github.com/Raku/Pod-To-HTML» for more information.
 
 =head2 X«{{podPath}}»
 
 It is replaced by the source url of the pod.
 
 =end pod
diff --git a/t/101-cli.t b/t/101-cli.t
@@ -19,19  19,23 @@ subtest 'setup assets' => {
     nok "documentable-assets".IO.e, "untar dir deleted";
 }
 
-# 'documentable setup' downloads a type-graph file different from the one 
 # 'documentable setup' downloads a type-graph file different from the one
 # used in the tests, so it needs to be deleted.
 unlink("type-graph.txt");
 
 subtest 'progress-bar-display' => {
     # We need to make sure the cache directory does not exist
     # It might fail if there's a change of version
     rmtree("t/.cache-test-doc");
 
     lives-ok {
             Documentable::CLI::MAIN('start', :topdir('t/test-doc'), :dirs('Language'), :p)
     }, "Lives";
 
     lives-ok {
-            Documentable::CLI::MAIN('start', :topdir('t/test-doc'),
-                    :dirs('Language'), :p)
-             },
-            "Lives";
         Documentable::CLI::MAIN('start', :topdir('t/test-doc'), :dirs('Types'),
         :p, :typegraph-file("t/test-doc/type-graph.txt"))
     }, "Lives";
 
     output-like {Documentable::CLI::MAIN('start', :topdir('t/test-doc'), :dirs('Language'), :p)},
                 /<!before \[\= \]?>/,

diff --git a/t/102-update.t b/t/102-update.t
@@ -70,7  70,13 @@ subtest 'not regenerate all subindexes' => {
 
 }
 
-rmtree("html");
 
 # ==================== see t/102-update_1.t =================================
 my $pod-path   = "t/test-doc/Language/terms.pod6";
 my $pod-string = $pod-path.IO.slurp;
 
 $pod-path.IO.spurt($pod-string.subst(/syntactic/, "CHANGED POD"));
 # ===========================================================================
 
 sub add-line($file) {
     $file ~ "\n # comment to modify the file"

diff --git a/t/102-update_1.t b/t/102-update_1.t
@@ -0,0  1,34 @@
 use Test;
 use File::Directory::Tree;
 
 use Documentable::CLI {};
 
 plan *;
 
 # Pod::From::Cached cannot return updated changes if those changes
 # have been applied while the Raku instance is runnig. Updates are only
 # taken into account if they have been made from different runs. For that
 # reason, to test this feature we need to modify the pod file in tha previous
 # test.
 
 subtest "New changes to pod are applied" => {
     my $pod-path   = "t/test-doc/Language/terms.pod6";
     my $pod-string = $pod-path.IO.slurp;
 
 
     Documentable::CLI::MAIN(
         'update',
         :topdir('t/test-doc'),
         :typegraph-file("t/test-doc/type-graph.txt"),
         :!verbose
     );
 
     my $html = "html/language/terms.html".IO.slurp;
     ok $html.contains("CHANGED POD");
 
     $pod-path.IO.spurt($pod-string.subst(/CHANGED\sPOD/, "syntactic"));
 }
 
 rmtree("html");
 
 done-testing;
diff --git a/t/301-registry.t b/t/301-registry.t
@@ -48,4  48,30 @@ subtest 'docs-for' => {
     is-deeply $registry.docs-for("int"), $doc, "basic search";
 }
 
 subtest "process-pod-dir" => {
 
     my $registry = Documentable::Registry.new(
         :topdir("t/test-doc"),
         :dirs([]),
     );
 
     lives-ok { $registry.process-pod-dir(:dir("Type")); }, "Lives";
 
     $registry.documentables = [];
     output-like { $registry.process-pod-dir(:dir("Type"))}, /"Processing Type directory..."/,
     "Lives and print message";
 
     my @expected = <Any Array Associative Cancellation Cool Hash Independent routines Map X::IO>;
     is $registry.documentables.map({.name}).sort, @expected, "All in Type dir processed";
 
     @expected = <Any Array Associative Cancellation Cool Hash Map X::IO independent-routines>;
     is $registry.documentables.map({.filename}).sort, @expected, "All filenames set";
 
     @expected = <Type/Any.pod6 Type/Array.pod6 Type/Associative.pod6 Type/Cancellation.pod6 Type/Cool.pod6
     Type/Hash.pod6 Type/Map.pod6 Type/X/IO.pod6 Type/independent-routines.pod6>;
     is $registry.documentables.map({.source-path}).sort.map({.IO.relative("t/test-doc")}),
     @expected, "All source-paths set";
 
 }
 
 done-testing;