General improves including comment formatting

2026-02-13 06:43:35 +00:00 · 2022-01-20 00:13:26 +00:00
parent 2b918ada4b
commit 5b97ff0b48
4 changed files with 202 additions and 103 deletions
--- a/tools/odin-html-docs/footer.txt.html
+++ b/tools/odin-html-docs/footer.txt.html
@@ -5,8 +5,8 @@
 	<div class="container pb-5 pt-5">
 		<div class="row g-4">
 		<div class="col">
-		<a class="navbar-brand" href="//odin-lang.org">
-		<img class="mb-3" src="//odin-lang.org/logo.svg" height="30" alt="Odin"></a>
+		<a class="navbar-brand" href="https://odin-lang.org">
+		<img class="mb-3" src="https://odin-lang.org/logo.svg" height="30" alt="Odin"></a>
 		<p>
 		The Data-Oriented Language for Sane Software Development.
 		</p>
@@ -14,8 +14,8 @@
 		<nav class="col-md-auto">
 			<h4 class="fw-normal">Resources</h4>
 			<ul class="list-unstyled">
-			<li><a href="//odin-lang.org/docs" class="link-light">Docs</a></li>
-			<li><a href="//odin-lang.org/news" class="link-light">Blog</a></li>
+			<li><a href="https://odin-lang.org/docs" class="link-light">Docs</a></li>
+			<li><a href="https://odin-lang.org/news" class="link-light">Blog</a></li>
 			</ul>
 		</nav>
 		<nav class="col-md-auto">
@@ -39,5 +39,6 @@
 	</div>
 </footer>

-<script src="//odin-lang.org/lib/bootstrap/js/bootstrap.min.js"></script>
-<script src="//odin-lang.org/js/script.js"></script>
+<script src="https://odin-lang.org/lib/bootstrap/js/bootstrap.min.js"></script>
+<script src="https://odin-lang.org/js/script.js"></script>
+<script>hljs.highlightAll()</script>
--- a/tools/odin-html-docs/header.txt.html
+++ b/tools/odin-html-docs/header.txt.html
@@ -3,32 +3,4 @@
 <head>
 	<meta charset="utf-8">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
-	<title>{0:s}</title>
-
-	<script type="text/javascript" src="https://livejs.com/live.js"></script>
-
-	<link rel="stylesheet" type="text/css" href="https://odin-lang.org/scss/custom.min.css">
-	<link rel="stylesheet" type="text/css" href="https://odin-lang.org/css/style.css">
-	<link rel="stylesheet" type="text/css" href="/style.css">
-
-	</style>
-</head>
-<body>
-<header class="sticky-top">
-	<nav class="navbar navbar-expand-lg navbar-dark bg-primary odin-menu">
-		<div class="container">
-			<a class="navbar-brand" href="/core">
-			<img src="//odin-lang.org/logo.svg" height="30" alt="Odin"></a>
-			<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#odin-navbar-content" aria-controls="odin-navbar-content" aria-expanded="false" aria-label="Toggle navigation"><span class="navbar-toggler-icon"></span></button>
-			<div class="collapse navbar-collapse" id="odin-navbar-content">
-			<ul class="navbar-nav ms-md-auto">
-				<li class="nav-item"><a class="nav-link" href="/core">Home</a></li>
-				<li class="nav-item"><a class="nav-link active" href="//odin-lang.org" aria-current="page">Language</a></li>
-				<li class="nav-item"><a class="nav-link" href="https://github.com/odin-lang/Odin" target="_blank">GitHub</a></li>
-			</ul>
-		</div>
-		</div>
-	</nav>
-</header>
-<main>
-<div class="container">
+	<title>{0:s}</title>
--- a/tools/odin-html-docs/odin_html_docs_main.odin
+++ b/tools/odin-html-docs/odin_html_docs_main.odin
@@ -9,6 +9,7 @@ import "core:path/slashpath"
 import "core:sort"
 import "core:slice"

+GITHUB_LICENSE_URL :: "https://github.com/odin-lang/Odin/tree/master/LICENSE"
 GITHUB_CORE_URL :: "https://github.com/odin-lang/Odin/tree/master/core"
 BASE_CORE_URL :: "/core"

@@ -90,6 +91,7 @@ recursive_make_directory :: proc(path: string, prefix := "") {

 write_html_header :: proc(w: io.Writer, title: string) {
 	fmt.wprintf(w, string(#load("header.txt.html")), title)
+	io.write(w, #load("header-lower.txt.html"))
 }

 write_html_footer :: proc(w: io.Writer, include_directory_js: bool) {
@@ -289,19 +291,28 @@ generate_directory_tree :: proc() -> (root: ^Dir_Node) {
 }

 write_core_directory :: proc(w: io.Writer) {
-
 	root := generate_directory_tree()

 	fmt.wprintln(w, `<div class="row odin-main">`)
 	defer fmt.wprintln(w, `</div>`)
+	{
+		fmt.wprintln(w, `<article class="col-lg-12 p-4">`)
+		fmt.wprintln(w, "<header>")
+		fmt.wprintln(w, "<h1>Core Library Collection</h1>")
+		fmt.wprintln(w, "<ul>")
+		fmt.wprintf(w, "<li>License: <a href=\"{0:s}\">BSD-3-Clause</a></li>\n", GITHUB_LICENSE_URL)
+		fmt.wprintf(w, "<li>Repository: <a href=\"{0:s}\">{0:s}</a></li>\n", GITHUB_CORE_URL)
+		fmt.wprintln(w, "</ul>")
+		fmt.wprintln(w, "</header>")
+		fmt.wprintln(w, "</article>")
+		fmt.wprintln(w, "<hr>")
+	}
 	fmt.wprintln(w, `<article class="col-lg-12 p-4">`)
 	defer fmt.wprintln(w, `</article>`)

-	fmt.wprintln(w, "<article>")
 	fmt.wprintln(w, "<header>")
-	fmt.wprintln(w, "<h1>Core Library Collection</h1>")
+	fmt.wprintln(w, `<h2><i class="bi bi-folder"></i>Directories</h2>`)
 	fmt.wprintln(w, "</header>")
-	fmt.wprintln(w, "</article>")

 	fmt.wprintln(w, "<div>")
 	fmt.wprintln(w, "\t<table class=\"doc-directory mt-4 mb-4\">")
@@ -802,57 +813,131 @@ write_docs :: proc(w: io.Writer, pkg: ^doc.Pkg, docs: string) {
 	if docs == "" {
 		return
 	}
-	it := docs
-	was_code := true
-	was_paragraph := true
-	prev_line: string
-	for line in strings.split_iterator(&it, "\n") {
-		text := strings.trim_space(line)
-		defer prev_line = line
+	Block_Kind :: enum {
+		Paragraph,
+		Code,
+	}
+	Block :: struct {
+		kind: Block_Kind,
+		lines: []string,
+	}

-		if strings.has_prefix(line, "\t") {
-			if !was_code {
-				was_code = true;
-				if prev_line == "Example:"  {
-					fmt.wprint(w, `<pre class="doc-code doc-code-example"><code>`)
-				} else {
-					fmt.wprint(w, `<pre class="doc-code"><code>`)
+	lines: [dynamic]string
+	it := docs
+	for line_ in strings.split_iterator(&it, "\n") {
+		line := strings.trim_right_space(line_)
+		append(&lines, line)
+	}
+
+	curr_block_kind := Block_Kind.Paragraph
+	start := 0
+	blocks: [dynamic]Block
+
+	for line, i in lines {
+		text := strings.trim_space(line)
+		switch curr_block_kind {
+		case .Paragraph:
+			if strings.has_prefix(line, "\t") {
+				if i-start > 0 {
+					append(&blocks, Block{curr_block_kind, lines[start:i]})
 				}
+				curr_block_kind, start = .Code, i
+			} else if text == "" {
+				if i-start > 0 {
+					append(&blocks, Block{curr_block_kind, lines[start:i]})
+				}
+				start = i
 			}
-			fmt.wprintf(w, "%s\n", strings.trim_prefix(line, "\t"))
-			continue
-		} else if was_code {
-			if text == "" {
+		case .Code:
+			if text == "" || strings.has_prefix(line, "\t") {
 				continue
 			}
-			was_code = false
-			fmt.wprintln(w, "</code></pre>")
-		}
-		if text == "" {

-			if was_paragraph {
-				was_paragraph = false
-				fmt.wprintln(w, "</p>")
+			if i-start > 0 {
+				append(&blocks, Block{curr_block_kind, lines[start:i]})
 			}
+			curr_block_kind, start = .Paragraph, i
+		}
+	}
+	if start < len(lines) {
+		if len(lines)-start > 0 {
+			append(&blocks, Block{curr_block_kind, lines[start:]})
+		}
+	}
+
+	for block in &blocks {
+		trim_amount := 0
+		for trim_amount = 0; trim_amount < len(block.lines); trim_amount += 1 {
+			line := block.lines[trim_amount]
+			if strings.trim_space(line) != "" {
+				break
+			}
+		}
+		block.lines = block.lines[trim_amount:]
+	}
+
+	for block, i in blocks {
+		if len(block.lines) == 0 {
 			continue
 		}
-		if !was_paragraph {
-			fmt.wprintln(w, "<p>")
+		prev_line := ""
+		if i > 0 {
+			prev_lines := blocks[i-1].lines
+			if len(prev_lines) > 0 {
+				prev_line = prev_lines[len(prev_lines)-1]
+			}
 		}
-		assert(!was_code)
+		prev_line = strings.trim_space(prev_line)

-		was_paragraph = true
-		write_doc_line(w, text)
+		lines := block.lines[:]

-		io.write_byte(w, '\n')
-	}
-	if was_code {
-		// assert(!was_paragraph, str(pkg.name))
-		was_code = false
-		fmt.wprintln(w, "</code></pre>")
-	}
-	if was_paragraph {
-		fmt.wprintln(w, "</p>")
+		end_line := block.lines[len(lines)-1]
+		if block.kind == .Paragraph && i+1 < len(blocks) {
+			if strings.has_prefix(end_line, "Example:") && blocks[i+1].kind == .Code {
+				lines = lines[:len(lines)-1]
+			}
+		}
+
+		switch block.kind {
+		case .Paragraph:
+			io.write_string(w, "<p>")
+			for line, line_idx in lines {
+				if line_idx > 0 {
+					io.write_string(w, "\n")
+				}
+				io.write_string(w, line)
+			}
+			io.write_string(w, "</p>\n")
+		case .Code:
+			all_blank := len(lines) > 0
+			for line in lines {
+				if strings.trim_space(line) != "" {
+					all_blank = false
+				}
+			}
+			if all_blank {
+				continue
+			}
+
+			if strings.has_prefix(prev_line, "Example:") {
+				io.write_string(w, "<details open class=\"code-example\">\n")
+				defer io.write_string(w, "</details>\n")
+				io.write_string(w, "<summary>Example:</summary>\n")
+				io.write_string(w, `<pre><code class="hljs" data-lang="odin">`)
+				for line in lines {
+					io.write_string(w, strings.trim_prefix(line, "\t"))
+					io.write_string(w, "\n")
+				}
+				io.write_string(w, "</code></pre>\n")
+			} else {
+				io.write_string(w, "<pre>")
+				for line in lines {
+					io.write_string(w, strings.trim_prefix(line, "\t"))
+					io.write_string(w, "\n")
+				}
+				io.write_string(w, "</pre>\n")
+			}
+		}
 	}
 }

@@ -860,7 +945,7 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 	fmt.wprintln(w, `<div class="row odin-main">`)
 	defer fmt.wprintln(w, `</div>`)

-	fmt.wprintln(w, `<article class="col-lg-9 p-4 documentation">`)
+	fmt.wprintln(w, `<article class="col-lg-9 p-4 documentation odin-article">`)

 	{ // breadcrumbs
 		fmt.wprintln(w, `<div class="row">`)
@@ -907,9 +992,7 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 	}

 	fmt.wprintln(w, `<h2>Index</h2>`)
-	fmt.wprintln(w, `<section class="doc-index" id="pkg-index">`)
-	// fmt.wprintln(w, `<a class="btn btn-primary" data-bs-toggle="collapse" href="#pkg-index" role="button" aria-expanded="true" aria-controls="pkg-index"><h2>Index</h2></a>`)
-	// fmt.wprintln(w, `<section class="doc-index collapse" id="pkg-index">`)
+	fmt.wprintln(w, `<div id="pkg-index">`)
 	pkg_procs:       [dynamic]^doc.Entity
 	pkg_proc_groups: [dynamic]^doc.Entity
 	pkg_types:       [dynamic]^doc.Entity
@@ -944,8 +1027,16 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 	slice.sort_by_key(pkg_consts[:],      entity_key)

 	write_index :: proc(w: io.Writer, name: string, entities: []^doc.Entity) {
-		fmt.wprintf(w, "<h3>%s</h3>\n", name)
-		fmt.wprintln(w, `<section class="doc-index">`)
+		fmt.wprintln(w, `<div>`)
+		defer fmt.wprintln(w, `</div>`)
+
+
+		fmt.wprintf(w, `<details open class="doc-index" id="doc-index-{0:s}" aria-labelledby="#doc-index-{0:s}-header">`+"\n", name)
+		fmt.wprintf(w, `<summary id="#doc-index-{0:s}-header">`+"\n", name)
+		io.write_string(w, name)
+		fmt.wprintln(w, `</summary>`)
+		defer fmt.wprintln(w, `</details>`)
+
 		if len(entities) == 0 {
 			io.write_string(w, "<p>This section is empty.</p>\n")
 		} else {
@@ -956,7 +1047,6 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 			}
 			fmt.wprintln(w, "</ul>")
 		}
-		fmt.wprintln(w, "</section>")
 	}

 	entity_ordering := [?]struct{name: string, entities: []^doc.Entity} {
@@ -972,7 +1062,7 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 		write_index(w, eo.name, eo.entities)
 	}

-	fmt.wprintln(w, "</section>")
+	fmt.wprintln(w, "</div>")


 	write_entity :: proc(w: io.Writer, e: ^doc.Entity) {
@@ -1008,6 +1098,7 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 			fmt.wprintf(w, "<div class=\"doc-source\"><a href=\"{0:s}\"><em>Source</em></a></div>", src_url)
 		}
 		fmt.wprintf(w, "</h3>\n")
+		fmt.wprintln(w, `<div>`)

 		switch e.kind {
 		case .Invalid, .Import_Name, .Library_Name:
@@ -1048,7 +1139,7 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 			init_string := str(e.init_string)
 			if init_string != "" {
 				io.write_string(w, " = ")
-				io.write_string(w, init_string)
+				io.write_string(w, "…")
 			}
 			fmt.wprintln(w, "</pre>")

@@ -1099,8 +1190,15 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 			fmt.wprintln(w, "</pre>")

 		}
+		fmt.wprintln(w, `</div>`)

-		write_docs(w, pkg, strings.trim_space(str(e.docs)))
+		the_docs := strings.trim_space(str(e.docs))
+		if the_docs != "" {
+			fmt.wprintln(w, `<details class="odin-doc-toggle" open>`)
+			fmt.wprintln(w, `<summary class="hideme"><span>&nbsp;</span></summary>`)
+			write_docs(w, pkg, the_docs)
+			fmt.wprintln(w, `</details>`)
+		}
 	}
 	write_entities :: proc(w: io.Writer, title: string, entities: []^doc.Entity) {
 		fmt.wprintf(w, "<h2 id=\"pkg-{0:s}\">{0:s}</h2>\n", title)
@@ -1109,7 +1207,9 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
 			io.write_string(w, "<p>This section is empty.</p>\n")
 		} else {
 			for e in entities {
+				fmt.wprintln(w, `<div class="pkg-entity">`)
 				write_entity(w, e)
+				fmt.wprintln(w, `</div>`)
 			}
 		}
 		fmt.wprintln(w, "</section>")
--- a/tools/odin-html-docs/style.css
+++ b/tools/odin-html-docs/style.css
@@ -25,10 +25,6 @@ table.`directory {
 	padding-right: 0;
 }

-.doc-directory tr[aria-controls]:hover {
-	background-color: #eee;
-}
-
 .doc-directory tr[aria-expanded=true] td.pkg-name:before {
 	content: "\2193";
 }
@@ -57,12 +53,12 @@ pre.doc-code {
 pre.doc-code a {
 	font-family: Consolas,Liberation Mono,Menlo,monospace!important;
 	text-decoration: none;
-	/*font-weight: bold;*/
-	color: #00bfd5;
+	color: #2179d8;
+	font-weight: 800;
 }

 pre.doc-code a.code-procedure {
-	color: #079300;
+	color: #047919;
 }

 .pkg-line-doc {
@@ -90,18 +86,48 @@ a > .a-hidden {
 a:hover > .a-hidden {
 	opacity: 100;
 }
-
-article.documentation h2 {
-	border-bottom: 1px dashed #c6c8ca;
-	padding-bottom: 0.5rem;
-}
 section.documentation h3 {
 	font-size: calc(1.1rem + .2vw);
 }

+.pkg-index h3 {
+	margin-top: 0  !important;
+	padding-top: 0 !important;
+}


-.doc-index h3 {
-	border-bottom: 1px solid #c6c8ca;
-	padding-bottom: 0.25rem;
+.documentation .pkg-entity {
+	padding-bottom: 0.75rem;
+	border-bottom: 1px solid #d0d0d0;
+}
+
+details.doc-index > summary {
+	position: relative;
+	font-size: 1.75rem;
+	left: -1.75rem;
+}
+details.doc-index ul {
+	list-style-type: none;
+}
+
+
+.odin-doc-toggle {
+
+}
+
+details.odin-doc-toggle[open] > summary.hideme {
+	margin-bottom: 0.5em;
+}
+
+details.odin-doc-toggle > summary.hideme {
+	cursor: pointer;
+}
+
+details.odin-doc-toggle[open] > summary.hideme span {
+	content: "";
+}
+
+
+details.code-example > summary {
+	font-weight: 700;
 }