docs: Fix building docs, and update ddox.

Author: Abscissa

CHANGELOG.md

@@ -23,6 +23,7 @@ Update from `vibe-d:core` to `vibe-core`, and various other improvements.
 - **Tests:** Fixed: USE_UNIT_THREADED envar doen't actually use unit-threaded.
 - **Tests:** Better diagnostics when using alternate `dub.selections.json`. (@SingingBush)
 - **Docs:** Add documentation and CI-related policies to `.travis.yml`.
+- **Docs:** Update modified ddox from 0.16.6 to 0.16.12.
 - **Internal:** [#212](https://github.com/mysql-d/mysql-native/issues/212):
     Add [.editorconfig](https://editorconfig.org/) file. (@schveiguy)
 

build-docs

@@ -1,4 +1,13 @@
 #!/bin/sh
+
+# Please use DMD 2.077.1 or below when building the documentation.
+#
+# DMD 2.078.0 and up causes lots of duplicated symbols in the documentation.
+# (See: https://github.com/rejectedsoftware/ddox/issues/208 )
+#
+# DMD 2.086.0 and up cause errors when building the docs because
+# gen-package-version and Scriptlike need updated.
+
 rdmd --build-only -c -Isource -Dddocs_tmp -X -Xfdocs/docs.json -version=MySQLDocs --force source/mysql/package.d
 rm -rf docs_tmp
 rm source/mysql/package.o

build-docs.bat

@@ -1,4 +1,13 @@
 @echo off
+
+rem  Please use DMD 2.077.1 or below when building the documentation.
+rem
+rem  DMD 2.078.0 and up causes lots of duplicated symbols in the documentation.
+rem  (See: https://github.com/rejectedsoftware/ddox/issues/208 )
+rem
+rem  DMD 2.086.0 and up cause errors when building the docs because
+rem  gen-package-version and Scriptlike need updated.
+
 rdmd --build-only -c -Isource -Dddocs_tmp -X -Xfdocs/docs.json -version=MySQLDocs --force source/mysql/package.d
 rmdir /S /Q docs_tmp > NUL 2> NUL
 del source\mysql\package.obj

ddox/.gitignore

@@ -2,6 +2,7 @@
 /ddox
 /__*
 node_modules
+ddox-test-library
 test/screenshots/*.diff.png
 test/screenshots/*.fail.png
 tests/*/test.json

ddox/.travis.yml

@@ -1,12 +1,9 @@
 language: d
-services:
-  - docker
+d: dmd-2.078.1
 addons:
   apt:
     packages:
     - libevent-dev
     - libssl-dev
-    - pkg-config
-    - zlib1g-dev
 
 script: ./travis-ci.sh

ddox/README-mysql-native.txt

@@ -1,13 +1,10 @@
 This copy of DDOX is included in the mysql-native repository for
 mysql-native's convenience.
 
-This is based on DDOX's 'v0.16.6' tag, with the following changes:
+This is based on DDOX's 'v0.16.12' tag, with the following changes:
 
 - Added this 'README-mysql-native.txt' file.
 
-- Modified 'dub.sdl' to include the version identifier 'VibeUseOpenSSL11' so
-it will succesfully link on my machine (Workaround DDOX Issue #186)
-
 - Modified 'layout.dt' and 'ddox.layout.dt' for mysql-native's purposes.
 (Workaround DDOX Issue #88)
 

ddox/dub.sdl

@@ -6,6 +6,16 @@ license "MIT"
 
 dependency "vibe-d:web" version=">=0.7.31 <0.9.0"
 dependency "hyphenate" version="~>1.1.0"
-dependency "libdparse" version="~>0.7.0"
+dependency "libdparse" version="~>0.8.0"
 
-versions "JsonLineNumbers" "VibeUseOpenSSL11"
+configuration "application" {
+	targetType "executable"
+	// Temporarily disabled to work around dlang/dub#1407
+	// mainSourceFile "source/app.d"
+	versions "JsonLineNumbers" "VibeNoSSL"
+}
+
+configuration "library" {
+	targetType "library"
+	excludedSourceFiles "source/app.d"
+}

ddox/dub.selections.json

@@ -1,18 +1,20 @@
 {
 	"fileVersion": 1,
 	"versions": {
-		"botan": "1.12.9",
+		"botan": "1.12.10",
 		"botan-math": "1.0.3",
-		"diet-ng": "1.4.3",
-		"eventcore": "0.8.17",
+		"diet-ng": "1.5.0",
+		"eventcore": "0.8.35",
 		"hyphenate": "1.1.1",
 		"libasync": "0.8.3",
-		"libdparse": "0.7.1",
+		"libdparse": "0.8.7",
 		"libevent": "2.0.2+2.0.16",
-		"memutils": "0.4.9",
-		"openssl": "1.1.5+1.0.1g",
-		"taggedalgebraic": "0.10.7",
-		"vibe-core": "1.2.0",
-		"vibe-d": "0.8.1"
+		"memutils": "0.4.11",
+		"mir-linux-kernel": "1.0.0",
+		"openssl": "1.1.6+1.0.1g",
+		"stdx-allocator": "2.77.2",
+		"taggedalgebraic": "0.10.11",
+		"vibe-core": "1.4.0",
+		"vibe-d": "0.8.4"
 	}
 }

ddox/source/ddox/api.d

@@ -247,7 +247,7 @@ string getAttributeString(Declaration decl, AttributeStringKind kind)
 
 enum AttributeStringKind { normal, functionPrefix, functionSuffix }
 
-string[] declStyleClasses(Declaration decl)
+auto declStyleClasses(Declaration decl)
 {
 	string[] ret;
 	ret ~= decl.protection.to!string().toLower();
@@ -257,7 +257,7 @@ string[] declStyleClasses(Declaration decl)
 		if (tdecl.type.attributes.canFind("@property")) ret ~= "property";
 		if (tdecl.type.attributes.canFind("static")) ret ~= "static";
 	}
-	return ret;
+	return ret.join(" ");
 }
 
 string formatType()(CachedType type, scope string delegate(in Entity) link_to, bool include_code_tags = true)
@@ -380,6 +380,10 @@ void renderTemplateArgs(R)(ref R output, Declaration decl, scope string delegate
 			output.put(' ');
 		}
 		output.put(arg.name);
+		if (arg.specValue.length) {
+			output.highlightDCode(" : ");
+			output.highlightDCode(arg.specValue);
+		}
 		if (arg.defaultValue.length) {
 			output.highlightDCode(" = ");
 			output.highlightDCode(arg.defaultValue);

ddox/source/ddox/ddoc.d

@@ -207,7 +207,7 @@ class DdocComment {
 
 		foreach (s; m_sections) {
 			if (display_section && !display_section(s.name)) continue;
-			parseSection(dst, s.name, s.lines, context, hlevel, allmacros);
+			parseSection(dst, s.name, s.lines.dup, context, hlevel, allmacros);
 		}
 	}
 

ddox/source/ddox/entities.d

@@ -507,7 +507,7 @@ final class TemplateDeclaration : Declaration {
 }
 
 final class TemplateParameterDeclaration : TypedDeclaration {
-	string defaultValue;
+	string defaultValue, specValue;
 
 	override @property string kindCaption() const { return "Template parameter"; }
 	override @property TemplateParameterDeclaration dup() { auto ret = new TemplateParameterDeclaration(parent, name); ret.copyFrom(this); ret.type = type; return ret; }

ddox/source/ddox/htmlgenerator.d

@@ -24,7 +24,7 @@ import vibe.core.stream;
 import vibe.data.json;
 import vibe.inet.path;
 import vibe.http.server;
-import vibe.stream.wrapper : StreamOutputRange;
+import vibe.stream.wrapper : streamOutputRange;
 import diet.html;
 import diet.traits : dietTraits;
 
@@ -40,7 +40,7 @@ import diet.traits : dietTraits;
 version (Windows) version = CaseInsensitiveFS;
 else version (OSX) version = CaseInsensitiveFS;
 
-void generateHtmlDocs(Path dst_path, Package root, GeneratorSettings settings = null)
+void generateHtmlDocs(NativePath dst_path, Package root, GeneratorSettings settings = null)
 {
 	import std.algorithm : splitter;
 	import vibe.web.common : adjustMethodStyle;
@@ -151,15 +151,20 @@ void generateHtmlDocs(Path dst_path, Package root, GeneratorSettings settings =
 		}
 	}
 
-	void writeHashedFile(Path filename, scope void delegate(OutputStream) del)
+	void writeHashedFile(NativePath filename, scope void delegate(OutputStream) del)
 	{
+		import std.range : drop, walkLength;
 		import vibe.stream.memory;
+
 		assert(filename.startsWith(dst_path));
 
 		auto str = createMemoryOutputStream();
 		del(str);
 		auto h = md5Of(str.data).toHexString.idup;
-		auto relfilename = filename[dst_path.length .. $].toString();
+		version (Have_vibe_core)
+			auto relfilename = NativePath(filename.bySegment.drop(dst_path.bySegment.walkLength)).toString();
+		else
+			auto relfilename = NativePath(filename.bySegment.drop(dst_path.bySegment.walkLength), false).toString();
 		auto ph = relfilename in file_hashes;
 		if (!ph || *ph != h) {
 			//logInfo("do write %s", filename);
@@ -168,26 +173,28 @@ void generateHtmlDocs(Path dst_path, Package root, GeneratorSettings settings =
 		new_file_hashes[relfilename] = h;
 	}
 
-	void visitModule(Module mod, Path pack_path)
+	void visitModule(Module mod, NativePath pack_path)
 	{
-		auto modpath = pack_path ~ PathEntry(mod.name);
+		import std.range : walkLength;
+
+		auto modpath = pack_path ~ NativePath.Segment(mod.name);
 		if (!existsFile(modpath)) createDirectory(modpath);
 		logInfo("Generating module: %s", mod.qualifiedName);
-		writeHashedFile(pack_path ~ PathEntry(mod.name~".html"), (stream) {
-			generateModulePage(stream, root, mod, settings, ent => linkTo(ent, pack_path.length-dst_path.length));
+		writeHashedFile(pack_path ~ NativePath.Segment(mod.name~".html"), (stream) {
+			generateModulePage(stream, root, mod, settings, ent => linkTo(ent, pack_path.bySegment.walkLength-dst_path.bySegment.walkLength));
 		});
 
 		DocGroup[][string] pages;
 		collectChildren(mod, pages);
 		foreach (name, decls; pages)
-			writeHashedFile(modpath ~ PathEntry(name~".html"), (stream) {
-				generateDeclPage(stream, root, mod, name, decls, settings, ent => linkTo(ent, modpath.length-dst_path.length));
+			writeHashedFile(modpath ~ NativePath.Segment(name~".html"), (stream) {
+				generateDeclPage(stream, root, mod, name, decls, settings, ent => linkTo(ent, modpath.bySegment.walkLength-dst_path.bySegment.walkLength));
 			});
 	}
 
-	void visitPackage(Package p, Path path)
+	void visitPackage(Package p, NativePath path)
 	{
-		auto packpath = p.parent ? path ~ PathEntry(p.name) : path;
+		auto packpath = p.parent ? path ~ NativePath.Segment(p.name) : path;
 		if( !packpath.empty && !existsFile(packpath) ) createDirectory(packpath);
 		foreach( sp; p.packages ) visitPackage(sp, packpath);
 		foreach( m; p.modules ) visitModule(m, packpath);
@@ -197,15 +204,15 @@ void generateHtmlDocs(Path dst_path, Package root, GeneratorSettings settings =
 
 	if( !dst_path.empty && !existsFile(dst_path) ) createDirectory(dst_path);
 
-	writeHashedFile(dst_path ~ PathEntry("index.html"), (stream) {
+	writeHashedFile(dst_path ~ NativePath.Segment("index.html"), (stream) {
 		generateApiIndex(stream, root, settings, ent => linkTo(ent, 0));
 	});
 
 	writeHashedFile(dst_path ~ "symbols.js", (stream) {
 		generateSymbolsJS(stream, root, settings, ent => linkTo(ent, 0));
 	});
 
-	writeHashedFile(dst_path ~ PathEntry("sitemap.xml"), (stream) {
+	writeHashedFile(dst_path ~ NativePath.Segment("sitemap.xml"), (stream) {
 		generateSitemap(stream, root, settings, ent => linkTo(ent, 0));
 	});
 
@@ -214,7 +221,7 @@ void generateHtmlDocs(Path dst_path, Package root, GeneratorSettings settings =
 	// delete obsolete files
 	foreach (f; file_hashes.byKey)
 		if (f !in new_file_hashes) {
-			try removeFile(dst_path ~ Path(f));
+			try removeFile(dst_path ~ NativePath(f));
 			catch (Exception e) logWarn("Failed to remove obsolete file '%s': %s", f, e.msg);
 		}
 
@@ -252,7 +259,8 @@ struct DdoxDietTraits(HTMLOutputStyle htmlStyle) {
 	enum HTMLOutputStyle htmlOutputStyle = htmlStyle;
 }
 
-void generateSitemap(OutputStream dst, Package root_package, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+void generateSitemap(OutputStream)(OutputStream dst, Package root_package, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+	if (isOutputStream!OutputStream)
 {
 	dst.write("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
 	dst.write("<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n");
@@ -266,10 +274,13 @@ void generateSitemap(OutputStream dst, Package root_package, GeneratorSettings s
 
 	void writeEntityRec(Entity ent){
 		import std.string;
-		if( !cast(Package)ent || ent is root_package ){
+		if (!cast(Package)ent || ent is root_package) {
 			auto link = link_to(ent);
-			if( indexOf(link, '#') < 0 ) // ignore URLs with anchors
-				writeEntry((settings.siteUrl ~ Path(link)).toString());
+			if (indexOf(link, '#') < 0) { // ignore URLs with anchors
+				auto p = InetPath(link);
+				p.normalize();
+				writeEntry((settings.siteUrl ~ p).toString());
+			}
 		}
 		ent.iterateChildren((ch){ writeEntityRec(ch); return true; });
 	}
@@ -280,13 +291,14 @@ void generateSitemap(OutputStream dst, Package root_package, GeneratorSettings s
 	dst.flush();
 }
 
-void generateSymbolsJS(OutputStream dst, Package root_package, GeneratorSettings settings, string delegate(in Entity) link_to)
+void generateSymbolsJS(OutputStream)(OutputStream dst, Package root_package, GeneratorSettings settings, string delegate(in Entity) link_to)
+	if (isOutputStream!OutputStream)
 {
 	import std.typecons : Tuple, tuple;
 
 	bool[Tuple!(Entity, CachedString)] visited;
 
-	auto rng = StreamOutputRange(dst);
+	auto rng = streamOutputRange(dst);
 
 	void writeEntry(Entity ent) {
 		auto key = tuple(ent.parent, ent.name);
@@ -316,15 +328,16 @@ void generateSymbolsJS(OutputStream dst, Package root_package, GeneratorSettings
 	rng.put("];\n");
 }
 
-void generateApiIndex(OutputStream dst, Package root_package, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+void generateApiIndex(OutputStream)(OutputStream dst, Package root_package, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+	if (isOutputStream!OutputStream)
 {
 	auto info = new DocPageInfo;
 	info.linkTo = link_to;
 	info.settings = settings;
 	info.rootPackage = root_package;
 	info.node = root_package;
 
-	auto rng = StreamOutputRange(dst);
+	auto rng = streamOutputRange(dst);
 	final switch (settings.htmlOutputStyle)
 	{
 		foreach (htmlOutputStyle; EnumMembers!HTMLOutputStyle)
@@ -336,7 +349,8 @@ void generateApiIndex(OutputStream dst, Package root_package, GeneratorSettings
 	}
 }
 
-void generateModulePage(OutputStream dst, Package root_package, Module mod, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+void generateModulePage(OutputStream)(OutputStream dst, Package root_package, Module mod, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+	if (isOutputStream!OutputStream)
 {
 	auto info = new DocPageInfo;
 	info.linkTo = link_to;
@@ -346,7 +360,7 @@ void generateModulePage(OutputStream dst, Package root_package, Module mod, Gene
 	info.node = mod;
 	info.docGroups = null;
 
-	auto rng = StreamOutputRange(dst);
+	auto rng = streamOutputRange(dst);
 	final switch (settings.htmlOutputStyle)
 	{
 		foreach (htmlOutputStyle; EnumMembers!HTMLOutputStyle)
@@ -358,7 +372,8 @@ void generateModulePage(OutputStream dst, Package root_package, Module mod, Gene
 	}
 }
 
-void generateDeclPage(OutputStream dst, Package root_package, Module mod, string nested_name, DocGroup[] docgroups, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+void generateDeclPage(OutputStream)(OutputStream dst, Package root_package, Module mod, string nested_name, DocGroup[] docgroups, GeneratorSettings settings, string delegate(in Entity) link_to, HTTPServerRequest req = null)
+	if (isOutputStream!OutputStream)
 {
 	import std.algorithm : sort;
 
@@ -372,7 +387,7 @@ void generateDeclPage(OutputStream dst, Package root_package, Module mod, string
 	sort!((a, b) => cmpKind(a.members[0], b.members[0]))(info.docGroups);
 	info.nestedName = nested_name;
 
-	auto rng = StreamOutputRange(dst);
+	auto rng = streamOutputRange(dst);
 	final switch (settings.htmlOutputStyle)
 	{
 		foreach (htmlOutputStyle; EnumMembers!HTMLOutputStyle)

ddox/source/ddox/main.d

@@ -53,7 +53,7 @@ int cmdGenerateHtml(string[] args)
 	if( auto ret = setupGeneratorInput(args, gensettings, pack) )
 		return ret;
 
-	generateHtmlDocs(Path(args[3]), pack, gensettings);
+	generateHtmlDocs(NativePath(args[3]), pack, gensettings);
 	return 0;
 }