From 1a0725f022299ab345a34250d37d25498664184a Mon Sep 17 00:00:00 2001
From: alaviss <leorize+oss@disroot.org>
Date: Thu, 25 Jun 2020 08:28:57 +0000
Subject: [PATCH] koch: add --localdocs to allow building only local docs
 (#14783)

* koch: add --localdocs to allow building only local docs

This flag also make koch doc use the passed arguments when building
the offline docs.

This is useful when generating nightlies as we would want to use
--doccmd:skip and also skipping a pass of docgen speed things up
drastically (for non-native targets).

This flag superseded the undocumented --docslocal.

* kochdocs: filter google analytics code from the arg list instead

This commit introduce a small PEG expression to filter out the google
analytics code before building local docs when --localdocs is not
specified. This lets us keep any arguments unrelated to google analytics
when building local docs, useful for use with --doccmd:skip
---
 koch.nim           | 20 +++++++++++---------
 tools/kochdocs.nim | 23 ++++++++++++++++++-----
 2 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/koch.nim b/koch.nim
index c1d8df8da..bbcb0e349 100644
--- a/koch.nim
+++ b/koch.nim
@@ -53,6 +53,8 @@ Options:
   --latest                 bundle the installers with a bleeding edge Nimble
   --stable                 bundle the installers with a stable Nimble (default)
   --nim:path               use specified path for nim binary
+  --localdocs[:path]       only build local documentations. If a path is not
+                           specified (or empty), the default is used.
 Possible Commands:
   boot [options]           bootstraps with given command line options
   distrohelper [bindir]    helper for distro packagers
@@ -642,7 +644,10 @@ proc showHelp() =
 
 when isMainModule:
   var op = initOptParser()
-  var latest = false
+  var
+    latest = false
+    localDocsOnly = false
+    localDocsOut = ""
   while true:
     op.next()
     case op.kind
@@ -651,19 +656,16 @@ when isMainModule:
       of "latest": latest = true
       of "stable": latest = false
       of "nim": nimExe = op.val.absolutePath # absolute so still works with changeDir
-      of "docslocal":
-        # undocumented for now, allows to rebuild local docs in < 40s as follows:
-        # `./koch --nim:$nimb --docslocal:htmldocs2 --doccmd:skip --warnings:off --hints:off`
-        # whereas `./koch docs` takes 190s; useful for development.
-        doAssert op.val.len > 0
-        buildDocsDir(op.cmdLineRest, op.val)
-        break
+      of "localdocs":
+        localDocsOnly = true
+        if op.val.len > 0:
+          localDocsOut = op.val.absolutePath
       else: showHelp()
     of cmdArgument:
       case normalize(op.key)
       of "boot": boot(op.cmdLineRest)
       of "clean": clean(op.cmdLineRest)
-      of "doc", "docs": buildDocs(op.cmdLineRest)
+      of "doc", "docs": buildDocs(op.cmdLineRest, localDocsOnly, localDocsOut)
       of "doc0", "docs0":
         # undocumented command for Araq-the-merciful:
         buildDocs(op.cmdLineRest & gaCode)
diff --git a/tools/kochdocs.nim b/tools/kochdocs.nim
index eacfb45ca..d0f8077ed 100644
--- a/tools/kochdocs.nim
+++ b/tools/kochdocs.nim
@@ -1,6 +1,6 @@
 ## Part of 'koch' responsible for the documentation generation.
 
-import os, strutils, osproc, sets, pathnorm
+import os, strutils, osproc, sets, pathnorm, pegs
 from std/private/globs import nativeToUnixPath, walkDirRecFilter, PathEntry
 import "../compiler/nimpaths"
 
@@ -182,7 +182,7 @@ lib/system/iterators.nim
 lib/system/dollars.nim
 lib/system/widestrs.nim
 """.splitWhitespace()
-  
+
   proc follow(a: PathEntry): bool =
     a.path.lastPathPart notin ["nimcache", "htmldocs", "includes", "deprecated", "genode"]
   for entry in walkDirRecFilter("lib", follow = follow):
@@ -318,6 +318,19 @@ proc buildDocsDir*(args: string, dir: string) =
   buildDocPackages(args, dir)
   copyFile(docHackJsSource, dir / docHackJsSource.lastPathPart)
 
-proc buildDocs*(args: string) =
-  buildDocsDir(args, webUploadOutput / NimVersion)
-  buildDocsDir("", docHtmlOutput) # no `args` to avoid offline docs containing the 'gaCode'!
+proc buildDocs*(args: string, localOnly = false, localOutDir = "") =
+  let localOutDir =
+    if localOutDir.len == 0:
+      docHtmlOutput
+    else:
+      localOutDir
+
+  var args = args
+
+  if not localOnly:
+    buildDocsDir(args, webUploadOutput / NimVersion)
+
+    let gaFilter = peg"@( y'--doc.googleAnalytics:' @(\s / $) )"
+    args = args.replace(gaFilter)
+
+  buildDocsDir(args, localOutDir)