Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
201: remove website generation code r=saem a=alaviss

## Summary
This pull purges the code related to Nim's website generation from the codebase.

## Details
The pieces being removed are:

- `koch`'s "web" doc generation, which has the following differences to "regular" docs:
  - Docs meant for publishing have Google Analytics (GA) enabled.
  - `nimblepkglist` was bundled to enable the display of the nimble catalogue in "Standard library" page. This feature is no longer used, even on Nim's published docs, since it is fairly slow and was not updated for the new docs layout. Alternative providers like  https://nimble.directory have completely superseded it.
- Google Analytics script injection in docgen: The script is injected whenever `--doc.googleAnalytics:<GA code>` is passed to `nim doc`.
- `nimweb`: A tool that appears to be used to generate the first generation of the Nim's website. Needless to say, it's pretty abandoned given the Jekyll-based version: https://github.com/nim-lang/website.

Closes nim-works#129 as this pull removes `nimblepkglist` as well, and the author of that PR is no longer responsive.

Co-authored-by: Leorize <[email protected]>
  • Loading branch information
bors[bot] and alaviss authored Jan 25, 2022
2 parents 36ad310 + d5fdfbf commit 7a872f4
Show file tree
Hide file tree
Showing 15 changed files with 5 additions and 998 deletions.
22 changes: 2 additions & 20 deletions compiler/tools/docgen.nim
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,6 @@ type
# in `doc.section.toc2`
toc: TocSectionsFinal # final TOC (wrapped in `doc.section.toc`)
indexValFilename: string
analytics: string # Google Analytics javascript, "" if doesn't exist
seenSymbols: StringTableRef # avoids duplicate symbol generation for HTML.
jEntriesPre: seq[JsonItem] # pre-processed RST + JSON content
jEntriesFinal: JsonNode # final JSON after RST pass 2 and rendering
Expand Down Expand Up @@ -315,22 +314,6 @@ proc newDocumentor*(filename: AbsoluteFile; cache: IdentCache; conf: ConfigRef,
conf.configVars, filename.string,
docgenFindFile, compilerMsgHandler)

if conf.configVars.hasKey("doc.googleAnalytics"):
result.analytics = """
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', '$1', 'auto');
ga('send', 'pageview');
</script>
""" % [conf.configVars.getOrDefault"doc.googleAnalytics"]
else:
result.analytics = ""

result.seenSymbols = newStringTable(modeCaseInsensitive)
result.id = 100
result.jEntriesFinal = newJArray()
Expand Down Expand Up @@ -1458,7 +1441,7 @@ proc genOutFile(d: PDoc, groupedToc = false): string =
"title", title, "subtitle", subtitle, "tableofcontents", toc,
"moduledesc", d.modDescFinal, "date", getDateStr(), "time", getClockStr(),
"content", content, "author", d.meta[metaAuthor],
"version", esc(d.target, d.meta[metaVersion]), "analytics", d.analytics,
"version", esc(d.target, d.meta[metaVersion]),
"deprecationMsg", d.modDeprecationMsg]
else:
code = content
Expand Down Expand Up @@ -1627,8 +1610,7 @@ proc commandBuildIndex*(conf: ConfigRef, dir: string, outFile = RelativeFile"")
"title", "Index",
"subtitle", "", "tableofcontents", "", "moduledesc", "",
"date", getDateStr(), "time", getClockStr(),
"content", content, "author", "", "version", "", "analytics", ""]
# no analytics because context is not available
"content", content, "author", "", "version", ""]

try:
writeFile(filename, code)
Expand Down
2 changes: 0 additions & 2 deletions config/nimdoc.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,6 @@ $content
doc.listing_start = "<pre$3 class=\"listing\">"
doc.listing_end = "</pre>"
# * $analytics: Google analytics location, includes <script> tags
doc.file = """<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Expand Down Expand Up @@ -290,7 +289,6 @@ window.addEventListener('DOMContentLoaded', main);
</div>
</div>
</div>
$analytics
</body>
</html>
"""
7 changes: 0 additions & 7 deletions doc/docgen.rst
Original file line number Diff line number Diff line change
Expand Up @@ -293,13 +293,6 @@ by default.
You can edit ``config/nimdoc.cfg`` and modify the ``doc.item.seesrc`` value
with a hyperlink to your own code repository.

In the case of Nim's own documentation, the `commit` value is just a commit
hash to append to a formatted URL to https://github.com/nim-lang/Nim. The
``tools/nimweb.nim`` helper queries the current git commit hash during the doc
generation, but since you might be working on an unpublished repository, it
also allows specifying a `githash` value in ``web/website.ini`` to force a
specific commit in the output.


Other Input Formats
===================
Expand Down
15 changes: 0 additions & 15 deletions doc/koch.rst
Original file line number Diff line number Diff line change
Expand Up @@ -68,21 +68,6 @@ driver of Nim's test suite. You can pass options to the `test`:option: command,
they will be forwarded to the tester. See its source code for available
options.

web command
-----------

The `web`:idx: command converts the documentation in the `doc` directory
from rst to HTML. It also repeats the same operation but places the result in
the ``web/upload`` which can be used to update the website at
https://nim-lang.org.

By default, the documentation will be built in parallel using the number of
available CPU cores. If any documentation build sub-commands fail, they will
be rerun in serial fashion so that meaningful error output can be gathered for
inspection. The `--parallelBuild:n`:option: switch or configuration option can be
used to force a specific number of parallel jobs or run everything serially
from the start (`n == 1`).

pdf command
-----------

Expand Down
1 change: 0 additions & 1 deletion nimdoc/rst2html/expected/rst_examples.html
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,5 @@ <h1><a class="toc-backref" id="introduction" href="#introduction">Introduction</
</div>
</div>
</div>

</body>
</html>
1 change: 0 additions & 1 deletion nimdoc/test_out_index_dot_html/expected/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,5 @@ <h1><a class="toc-backref" href="#12">Procs</a></h1>
</div>
</div>
</div>

</body>
</html>
1 change: 0 additions & 1 deletion nimdoc/test_out_index_dot_html/expected/theindex.html
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,5 @@ <h1 class="title">Index</h1>
</div>
</div>
</div>

</body>
</html>
1 change: 0 additions & 1 deletion nimdoc/testproject/expected/subdir/subdir_b/utils.html
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,5 @@ <h1><a class="toc-backref" href="#18">Templates</a></h1>
</div>
</div>
</div>

</body>
</html>
1 change: 0 additions & 1 deletion nimdoc/testproject/expected/testproject.html
Original file line number Diff line number Diff line change
Expand Up @@ -1082,6 +1082,5 @@ <h1><a class="toc-backref" href="#18">Templates</a></h1>
</div>
</div>
</div>

</body>
</html>
1 change: 0 additions & 1 deletion nimdoc/testproject/expected/theindex.html
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,5 @@ <h1 class="title">Index</h1>
</div>
</div>
</div>

</body>
</html>
27 changes: 1 addition & 26 deletions tools/koch/koch.nim
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,6 @@ Options:
external components (default).
--nim:path use specified path for nim binary. This can also be used to
override the bootstrapping compiler.
--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
Expand Down Expand Up @@ -86,9 +84,6 @@ Commands for core developers:
specifying a category, e.g. `tests cat async`)
temp options creates a temporary compiler for testing
testTools run tooling testsuite
Web options:
--googleAnalytics:UA-... add the given google analytics code to the docs. To
build the official docs, use UA-48159761-1
"""

# Set the compiler source location to what is given by `koch.py`.
Expand Down Expand Up @@ -270,20 +265,6 @@ proc binArchive(target: BinArchiveTarget, args: string) =

archive(binaryArgs & " " & args)

when false:
proc web(args: string) =
nimexec("js tools/dochack/dochack.nim")
nimexec("cc -r tools/nimweb.nim $# web/website.ini --putenv:nimversion=$#" %
[args, VersionAsString])

proc website(args: string) =
nimexec("cc -r tools/nimweb.nim $# --website web/website.ini --putenv:nimversion=$#" %
[args, VersionAsString])

proc pdf(args="") =
exec("$# cc -r tools/nimweb.nim $# --pdf web/website.ini --putenv:nimversion=$#" %
[findNim().quoteShell(), args, VersionAsString], additionalPATH=findNim().splitFile.dir)

# -------------- boot ---------------------------------------------------------

proc findStartNim: string =
Expand Down Expand Up @@ -650,8 +631,6 @@ when isMainModule:
var op = initOptParser()
var
latest = false
localDocsOnly = false
localDocsOut = ""

# Set SOURCE_DATE_EPOCH to cover other tooling that might make use of the
# current time. Currently these tools are known to use the current time:
Expand All @@ -669,16 +648,12 @@ when isMainModule:
of "latest": latest = true
of "stable": latest = false
of "nim": nimExe = op.val.absolutePath # absolute so still works with changeDir
of "localdocs":
localDocsOnly = true
if op.val.len > 0:
localDocsOut = op.val.absolutePath
else: showHelp(success = false)
of cmdArgument:
case normalize(op.key)
of "boot": boot(op.cmdLineRest)
of "clean": clean(op.cmdLineRest)
of "doc", "docs": buildDocs(op.cmdLineRest, localDocsOnly, localDocsOut)
of "doc", "docs": buildDocs(op.cmdLineRest)
of "pdf": buildPdfDoc(op.cmdLineRest, "doc/pdf")
of "csource", "csources": csource(op.cmdLineRest)
of "winrelease": binArchive(Windows, op.cmdLineRest)
Expand Down
22 changes: 2 additions & 20 deletions tools/koch/kochdocs.nim
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ const
nimArgs = "--errormax:3 --hint:Conf:off --hint:Path:off --hint:Processing:off --hint:XDeclaredButNotUsed:off --warning:UnusedImport:off -d:boot $#" % [docDefines]
gitUrl = "https://github.com/nim-works/nimskull"
docHtmlOutput = "doc/html"
webUploadOutput = "web/upload"

var nimExe*: string
var nimSource*: string
Expand Down Expand Up @@ -438,9 +437,6 @@ proc buildPdfDoc*(nimArgs, destPath: string) =

proc buildJS(): string =
let nim = findNim()
exec("$# js -d:release --out:$# tools/nimblepkglist.nim" %
[nim.quoteShell(), webUploadOutput / "nimblepkglist.js"])
# xxx deadcode? and why is it only for webUploadOutput, not for local docs?
result = getDocHacksJs(nimr = getCurrentDir(), nim)

proc buildDocsDir*(args: string, dir: string) =
Expand All @@ -457,23 +453,9 @@ proc buildDocsDir*(args: string, dir: string) =
buildDocPackages(args, dir)
copyFile(docHackJsSource, dir / docHackJsSource.lastPathPart)

proc buildDocs*(args: string, localOnly = false, localOutDir = "") =
let localOutDir =
if localOutDir.len == 0:
docHtmlOutput
else:
localOutDir

proc buildDocs*(args: string) =
nimKeywordsBuildCheck()

var args = args

if not localOnly:
buildDocsDir(args, webUploadOutput / NimVersion)

# XXX: Remove this feature check once the csources supports it.
when defined(nimHasCastPragmaBlocks):
let gaFilter = peg"@( y'--doc.googleAnalytics:' @(\s / $) )"
args = args.replace(gaFilter)

buildDocsDir(args, localOutDir)
buildDocsDir(args, docHtmlOutput)
80 changes: 0 additions & 80 deletions tools/nimblepkglist.nim

This file was deleted.

Loading

0 comments on commit 7a872f4

Please sign in to comment.