From 2f610d621f52fe83863c19ac65f7e1336bce838d Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Sat, 25 May 2019 14:20:25 -0400 Subject: [PATCH] Use the correct HTML file reference in "nim doc" generated idx files (#11326) * Use the correct HTML file reference in "nim doc" generated idx files Now "nim doc --out:foo.html --index:on bar.nim" generates "foo.html" and the generated "bar.idx" contains references to "foo.html". Fixes https://github.com/nim-lang/Nim/issues/11325. * Refactor the nim doc tester to extend it for more tests * Reference the HTML files relative to the outDir, not project dir * Add test for issues #11312 and #11325 - https://github.com/nim-lang/Nim/issues/11312 - https://github.com/nim-lang/Nim/issues/11325 --- compiler/docgen.nim | 2 +- .../test_out_index_dot_html/expected/foo.idx | 1 + .../expected/index.html | 850 ++++++++++++++++++ .../expected/theindex.html | 808 +++++++++++++++++ nimdoc/test_out_index_dot_html/foo.nim | 3 + nimdoc/tester.nim | 63 +- 6 files changed, 1716 insertions(+), 11 deletions(-) create mode 100644 nimdoc/test_out_index_dot_html/expected/foo.idx create mode 100644 nimdoc/test_out_index_dot_html/expected/index.html create mode 100644 nimdoc/test_out_index_dot_html/expected/theindex.html create mode 100644 nimdoc/test_out_index_dot_html/foo.nim diff --git a/compiler/docgen.nim b/compiler/docgen.nim index bfd09895a6..f5762ca4d2 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -670,7 +670,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) = [nameRope, result, comm, itemIDRope, plainNameRope, plainSymbolRope, symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, seeSrcRope])) - let external = AbsoluteFile(d.filename).relativeTo(d.conf.projectPath, '/').changeFileExt(HtmlExt).string + let external = AbsoluteFile(d.destFile).relativeTo(d.conf.outDir, '/').changeFileExt(HtmlExt).string var attype: Rope if k in routineKinds and nameNode.kind == nkSym: diff --git a/nimdoc/test_out_index_dot_html/expected/foo.idx b/nimdoc/test_out_index_dot_html/expected/foo.idx new file mode 100644 index 0000000000..a8dabb67e0 --- /dev/null +++ b/nimdoc/test_out_index_dot_html/expected/foo.idx @@ -0,0 +1 @@ +foo index.html#foo foo: foo() diff --git a/nimdoc/test_out_index_dot_html/expected/index.html b/nimdoc/test_out_index_dot_html/expected/index.html new file mode 100644 index 0000000000..8ee7dfd22f --- /dev/null +++ b/nimdoc/test_out_index_dot_html/expected/index.html @@ -0,0 +1,850 @@ + + + + + + + + + + + + + + + + + +foo + + + + + + + + +
+
+

foo

+
+
+ +
+ Search: +
+
+ Group by: + +
+ + +
+
+
+

+
+

Procs

+
+ +
proc foo() {...}{.raises: [], tags: [].}
+
+I do foo + +
+ +
+ +
+
+ +
+
+ +
+ Made with Nim. Generated: 1970-01-02 03:46:40 UTC +
+
+
+
+ + + diff --git a/nimdoc/test_out_index_dot_html/expected/theindex.html b/nimdoc/test_out_index_dot_html/expected/theindex.html new file mode 100644 index 0000000000..9213f14590 --- /dev/null +++ b/nimdoc/test_out_index_dot_html/expected/theindex.html @@ -0,0 +1,808 @@ + + + + + + + + + + + + + + + + + +Index + + + + + + + + +
+
+

Index

+ Modules: index.

API symbols

+
foo:
+
+
+
+ +
+ Made with Nim. Generated: 1970-01-02 03:46:40 UTC +
+
+
+
+ + + diff --git a/nimdoc/test_out_index_dot_html/foo.nim b/nimdoc/test_out_index_dot_html/foo.nim new file mode 100644 index 0000000000..f61995eb9c --- /dev/null +++ b/nimdoc/test_out_index_dot_html/foo.nim @@ -0,0 +1,3 @@ +proc foo*() = + ## I do foo + echo "foo says hello!" diff --git a/nimdoc/tester.nim b/nimdoc/tester.nim index 997ed85962..43e146fafb 100644 --- a/nimdoc/tester.nim +++ b/nimdoc/tester.nim @@ -1,20 +1,36 @@ # Small program that runs the test cases for 'nim doc'. +# To run this, cd to the git repo root, and run "nim c -r nimdoc/tester.nim". import strutils, os var failures = 0 -proc test(dir: string; fixup = false) = +const + baseDir = "nimdoc" + +type + NimSwitches = object + doc: seq[string] + buildIndex: seq[string] + +proc testNimDoc(prjDir, docsDir: string; switches: NimSwitches; fixup = false) = + let + nimDocSwitches = switches.doc.join(" ") + nimBuildIndexSwitches = switches.buildIndex.join(" ") + putEnv("SOURCE_DATE_EPOCH", "100000") - if execShellCmd("nim doc --project --index:on -o:$1/htmldocs $1/testproject.nim" % dir) != 0: - quit("FAILURE: nim doc failed") - if execShellCmd("nim buildIndex -o:$1/htmldocs/theindex.html $1/htmldocs" % [dir]) != 0: - quit("FAILURE: nim buildIndex failed") + if nimDocSwitches != "": + if execShellCmd("nim doc $1" % [nimDocSwitches]) != 0: + quit("FAILURE: nim doc failed") - for expected in walkDirRec(dir / "expected/"): - let produced = expected.replace('\\', '/').replace("/expected/", "/htmldocs/") + if nimBuildIndexSwitches != "": + if execShellCmd("nim buildIndex $1" % [nimBuildIndexSwitches]) != 0: + quit("FAILURE: nim buildIndex failed") + + for expected in walkDirRec(prjDir / "expected/"): + let produced = expected.replace('\\', '/').replace("/expected/", "/$1/" % [docsDir]) if not fileExists(produced): echo "FAILURE: files not found: ", produced inc failures @@ -26,8 +42,35 @@ proc test(dir: string; fixup = false) = copyFile(produced, expected) else: echo "SUCCESS: files identical: ", produced - if failures == 0: - removeDir(dir / "htmldocs") -test("nimdoc/testproject", defined(fixup)) + if failures == 0 and ((prjDir / docsDir) != prjDir): + removeDir(prjDir / docsDir) + +# Test "nim doc --project --out:.. --index:on .." +let + test1PrjName = "testproject" + test1Dir = baseDir / test1PrjName + test1DocsDir = "htmldocs" + test1Switches = NimSwitches(doc: @["--project", + "--out:$1/$2" % [test1Dir, test1DocsDir], + "--index:on", + "$1/$2.nim" % [test1Dir, test1PrjName]], + buildIndex: @["--out:$1/$2/theindex.html" % [test1Dir, test1DocsDir], + "$1/$2" % [test1Dir, test1DocsDir]]) +testNimDoc(test1Dir, test1DocsDir, test1Switches, defined(fixup)) + +# Test "nim doc --out:.. --index:on .." +let + test2PrjDir = "test_out_index_dot_html" + test2PrjName = "foo" + test2Dir = baseDir / test2PrjDir + test2DocsDir = "htmldocs" + test2Switches = NimSwitches(doc: @["--out:$1/$2/index.html" % [test2Dir, test2DocsDir], + "--index:on", + "$1/$2.nim" % [test2Dir, test2PrjName]], + buildIndex: @["--out:$1/$2/theindex.html" % [test2Dir, test2DocsDir], + "$1/$2" % [test2Dir, test2DocsDir]]) +testNimDoc(test2Dir, test2DocsDir, test2Switches, defined(fixup)) + +# Check for failures if failures > 0: quit($failures & " failures occurred.")