Merge pull request #47 from antoniogamiz/updateoption

Updateoption, close #46
antoniogamiz · Jul 15, 2019 · f21f578 · f21f578
2 parents 0be7a4d + 30763fe
commit f21f578
Show file tree

Hide file tree

Showing 8 changed files with 220 additions and 15 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -29,6 +29,10 @@ variables:
         documentable setup
         documentable start --topdir=test-doc -v -p -s -k -i
         linkhealth --doc-dir=html
+
+        # update option
+        echo "dd" >> test-doc/Type/Any.pod6
+        documentable update --topdir=test-doc
 jobs:
   test-linux:
     <<: *linux

diff --git a/META6.json b/META6.json
@@ -21,12 +21,13 @@
   "name": "Perl6::Documentable",
   "perl": "6.c",
   "provides": {
+    "Perl6::Documentable": "lib/Perl6/Documentable.pm6",
     "Perl6::Documentable::CLI": "lib/Perl6/Documentable/CLI.pm6",
+    "Perl6::Documentable::Update": "lib/Perl6/Documentable/Update.pm6",
+    "Perl6::Documentable::Registry": "lib/Perl6/Documentable/Registry.pm6",
     "Perl6::Documentable::Processing": "lib/Perl6/Documentable/Processing.pm6",
     "Perl6::Documentable::Processing::Grammar": "lib/Perl6/Documentable/Processing/Grammar.pm6",
     "Perl6::Documentable::Processing::Actions": "lib/Perl6/Documentable/Processing/Actions.pm6",
-    "Perl6::Documentable": "lib/Perl6/Documentable.pm6",
-    "Perl6::Documentable::Registry": "lib/Perl6/Documentable/Registry.pm6",
     "Perl6::Documentable::To::HTML": "lib/Perl6/Documentable/To/HTML.pm6",
     "Perl6::Documentable::To::HTML::Wrapper": "lib/Perl6/Documentable/To/HTML/Wrapper.pm6",
     "Perl6::Utils": "lib/Perl6/Utils.pm6"

diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@ In this repository you can find all logic responsible of generate the [official
   - [Consulting methods](#consulting-methods)
   - [Indexing methods](#indexing-methods)
 - [Perl6::Documentable::Processing](#perl6documentableprocessing)
+- [Perl6::Documentable::Update](#perl6documentableupdate)
 - [Perl6::Documentable::To::HTML::Wrapper](#perl6documentabletohtmlwrapper)
 - [Perl6::Documentable::To::HTML](#perl6documentabletohtml)
 - [Perl6::Utils](#perl6utils)
@@ -34,13 +35,19 @@ Before generate any documents you should execute:
 documentable setup
 ```
 
-in order to download the necessary files to the site (CSS, svg, ...). Alternatively, you can add your own.
+in order to download the necessary files to generate the site (CSS, svg, ...). Alternatively, you can add your own.
 
 ```
+# setup the working directory
 documentable setup
+
+# generate the documentation
 documentable start [--topdir=<Str>] [-v|--verbose] [-c|--cache] [-p|--pods] [-s|--search-index]
                   [-i|--indexes] [-t|--type-images] [-f|--force] [-a|--all] [--highlight]
                   [-k|--kind] [--manage]
+
+# update the documentation when a pod file has been modified
+documentable update [--topdir=<Str>]
 ```
 
 #### --topdir <Str>
@@ -838,6 +845,65 @@ That's done for every element in meta, that means, if meta has 2 elements, then
 
 If there is no meta part, then the pod content is taken as name.
 
+## Perl6::Documentable::Update
+
+This module is responsible of updating the HTML documents of those files that have changed.
+
+#### sub update-pod-collection
+
+```perl6
+sub update-pod-collection (
+    Str        :$topdir,
+    Array[Str] :$filenames
+) return Mu
+```
+
+Updates all HTML documents in filenames using update-file.
+
+#### sub update-indexes
+
+```perl6
+sub update-indexes(
+    Array[Str]                      @kinds,
+    Perl6::Documentable::Registry   $registry
+) return Mu
+```
+
+Regenerates those indexes related to a given kinds.
+
+#### sub update-file
+
+```perl6
+sub update-file (
+    Str                           $filename,
+    Perl6::Documentable::Registry $registry
+) return Mu
+```
+
+Given the name of a modified file, regenerates and rewrite all HTML documents related/coming from this file.
+
+#### sub update-per-kind-files
+
+```perl6
+sub update-per-kind-files (
+    Str                 $kind,
+    Perl6::Documentable $doc,
+    Hash                %documentables
+) return Mu
+```
+
+Given a kind and a Perl6::Documentable object, regenerates and rewrites all files related to that kind, related to \$doc.
+
+#### sub update-registry
+
+```perl6
+sub update-registry (
+    Str :$topdir
+) return Perl6::Documentable::Registry
+```
+
+Reprocess the pod collection and returns an updated [Perl6::Documentable::Registry](#perl6documentableregistry) object.
+
 ## Perl6::Documentable::To::HTML::Wrapper
 
 This module takes a pod and wrap it in our HTML template, adding a header and a footer. Each and every one of the files generated comes from `p2h`.

diff --git a/lib/Perl6/Documentable/CLI.pm6 b/lib/Perl6/Documentable/CLI.pm6
@@ -2,6 +2,7 @@ use v6;
 
 use File::Temp;
 use Perl6::Utils;
+use Perl6::Documentable::Update;
 use Perl6::Documentable::Processing;
 use Perl6::Documentable::To::HTML;
 use Perl6::Documentable::To::HTML::Wrapper;
@@ -181,6 +182,33 @@ package Perl6::Documentable::CLI {
         }
 
     }
+
+    #| Check which pod files have changed and regenerate its HTML files.
+    multi MAIN (
+        "update",
+        :$topdir = "doc" #= Directory where is stored the pod collection
+    ) {
+        DEBUG("Checking for changes...");
+        my $program = "use Pod::To::Cached; Pod::To::Cached.new(:source('cache'), :verbose).update-cache;";
+        my $proc   = run("perl6", "-e", $program, :out, :err);
+        my @lines = $proc.err.slurp(:close).Str.split("\n");
+
+        if (+@lines > 4) {
+            # firsts and lasts two lines are useless output
+            @lines = @lines = @lines.Array[2, *-3].unique;
+            # format: Caching namefile
+            my @modified = @lines.map({.split(" ")[1]});
+            @modified = @modified.map({ .split("/")[*-1].tc });
+
+            DEBUG(+@modified ~ " file(s) modified. Starting regeneratiion ...");
+
+            my $now = now;
+            update-pod-collection(:$topdir, :filenames(@modified));
+            print-time("Updating files", $now);
+        } else {
+            DEBUG("Everything already updated. There are no changes.")
+        }
+    }
 }
 
 
@@ -219,14 +247,4 @@ sub highlight-code-blocks {
         await $promise;
         $promise.result;
     }
-}  
-
-sub print-time($phase, $start) {
-    my $now = now;
-    say "\e[1;36m$phase has taken {$now-$start} seconds \e[0m";
-}
-
-# debug function
-sub DEBUG($msg, $v = True) {
-    say $msg if $v;
 }
diff --git a/lib/Perl6/Documentable/To/HTML.pm6 b/lib/Perl6/Documentable/To/HTML.pm6
@@ -46,7 +46,7 @@ sub generate-kind-file($name, @docs, $kind) is export {
             .pod.list,
         })
     );
-    [$name, p2h($pod, $kind)];
+    return [$name, p2h($pod, $kind)];
 }
 
 sub generate-kind($registry, $kind) is export {

diff --git a/lib/Perl6/Documentable/Update.pm6 b/lib/Perl6/Documentable/Update.pm6
@@ -0,0 +1,104 @@
+use v6.c;
+
+unit class Perl6::Documentable::Update;
+
+use Perl6::Utils;
+use Perl6::Documentable::Processing;
+use Perl6::Documentable::To::HTML;
+
+#| Updates all HTML documents in filenames using update-file.
+sub update-pod-collection(:$topdir, :$filenames) is export {
+    my @filenames = $filenames ~~ Positional ?? @$filenames !! [$filenames];
+    my $registry = update-registry(:$topdir);
+
+    my @kinds = @filenames.map({update-file($_, $registry)}).unique;
+
+    update-indexes(@kinds, $registry);
+}
+
+#| Regenerates those indexes related to a given kinds.
+sub update-indexes(@kinds, $registry) {
+    spurt 'html/routine.html', routine-index-html($registry.routine-index);
+    for <sub method term operator trait submethod> -> $category {
+        DEBUG("Writing html/routine-$category.html ...");
+        spurt "html/routine-$category.html", 
+        routine-subindex-html($registry.routine-subindex(:$category), $category);        
+    }
+    for @kinds -> $kind {
+        given $kind {
+            when "type" {
+                DEBUG("Writing html/type.html ...");
+                spurt 'html/type.html', type-index-html($registry.type-index);
+                for <basic composite domain-specific exceptions> -> $category {
+                    DEBUG("Writing html/type-$category.html ...");
+                    spurt "html/type-$category.html", 
+                    type-subindex-html($registry.type-subindex(:$category), $category);        
+                }
+            }
+            when "language" {
+                DEBUG("Writing html/language.html ...");
+                spurt 'html/language.html', language-index-html($registry.language-index, True);
+
+            }
+            when "programs" {
+                DEBUG("Writing html/programs.html ...");
+                spurt 'html/programs.html', programs-index-html($registry.programs-index);
+            }
+        }
+    }
+}
+
+#| Given the name of a modified file, regenerates and rewrite all HTML documents
+#| related/coming from this file.
+sub update-file($filename, $registry) {
+    state %syntax-docs  = $registry.lookup("syntax", :by<kind>)
+                                   .categorize({.name});
+    state %routine-docs = $registry.lookup("routine", :by<kind>)
+                                   .categorize({.name});
+    my $doc = $registry.documentables.grep({.pod-is-complete})
+              .grep({ 
+                  .url.split("/")[*-1] eq $filename || # language/something
+                  .url.split("/")[*-1] eq $filename.tc # type/Class
+               }).first;
+
+    # source file
+    spurt "html{$doc.url}.html", source-html($doc.kind,$doc);
+
+    # syntax files
+    update-per-kind-files("syntax", $doc, %syntax-docs);
+    # routine files
+    update-per-kind-files("routine", $doc, %routine-docs);    
+
+    # used by update-pod-collection to regenerate the indexes
+    return $doc.kind; 
+}
+
+#| Given a kind and a Perl6::Documentable object, regenerates and rewrites
+#| all files related to that kind, related to $doc.
+sub update-per-kind-files($kind, $doc, %documentables) {
+    my @kind-docs = $doc.defs.grep({.kind eq $kind})
+                               .map({.name});
+    @kind-docs = @kind-docs.map(-> $name {
+        generate-kind-file($name, %documentables{$name}, $kind)
+    });
+    for @kind-docs {
+        spurt "html/$kind/{replace-badchars-with-goodnames .[0]}.html", .[1];
+    }
+}
+
+#| Reprocess the pod collection and returns an updated Perl6::Registry object.
+sub update-registry(:$topdir) {
+    my $now = now;
+    DEBUG("Processing the collection...");
+    my $registry = process-pod-collection(
+        :cache,
+        :!verbose,
+        :$topdir,
+        dirs => ["Language", "Type", "Programs", "Native"]
+    );
+    $registry.compose;
+    print-time("Processing the collection", $now);
+    return $registry;
+}
+
+# vim: expandtab shiftwidth=4 ft=perl6
diff --git a/lib/Perl6/Utils.pm6 b/lib/Perl6/Utils.pm6
@@ -144,4 +144,14 @@ sub find-p5to6-functions(:$pod!, :%functions) is export {
           find-p5to6-functions(:pod($sub-pod), :%functions) if $sub-pod ~~ Pod::Block;
       }
   }
+}
+
+sub print-time($phase, $start) is export {
+    my $now = now;
+    say "\e[1;36m$phase has taken {$now-$start} seconds \e[0m";
+}
+
+# debug function
+sub DEBUG($msg, $v = True) is export {
+    say $msg if $v;
 }
diff --git a/t/001-load.t b/t/001-load.t
@@ -1,10 +1,11 @@
 use v6.c;
 use Test;
 
-plan 8;
+plan 9;
 
 use Perl6::Utils;
 use Perl6::Documentable;
+use Perl6::Documentable::Update;
 use Perl6::Documentable::Registry;
 use Perl6::Documentable::To::HTML;
 use Perl6::Documentable::To::HTML::Wrapper;
@@ -14,6 +15,7 @@ use Perl6::Documentable::Processing::Actions;
 
 use-ok 'Perl6::Utils';
 use-ok 'Perl6::Documentable';
+use-ok 'Perl6::Documentable::Update';
 use-ok 'Perl6::Documentable::Registry';
 use-ok 'Perl6::Documentable::To::HTML';
 use-ok 'Perl6::Documentable::To::HTML::Wrapper';