ed/Odin
1
0
Fork 0
mirror of https://github.com/Ed94/Odin.git synced 2026-08-04 22:58:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

General improves including comment formatting

Browse Source
This commit is contained in:
gingerBill
2022-01-20 00:13:26 +00:00
parent 2b918ada4b
commit 5b97ff0b48
4 changed files with 202 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/odin-html-docs/footer.txt.html
+7 -6
View File
@@ -5,8 +5,8 @@
<div class="container pb-5 pt-5"> <div class="container pb-5 pt-5">
<div class="row g-4"> <div class="row g-4">
<div class="col"> <div class="col">
<a class="navbar-brand" href="//odin-lang.org"> <a class="navbar-brand" href="https://odin-lang.org">
<img class="mb-3" src="//odin-lang.org/logo.svg" height="30" alt="Odin"></a> <img class="mb-3" src="https://odin-lang.org/logo.svg" height="30" alt="Odin"></a>
<p> <p>
The Data-Oriented Language for Sane Software Development. The Data-Oriented Language for Sane Software Development.
</p> </p>
@@ -14,8 +14,8 @@
<nav class="col-md-auto"> <nav class="col-md-auto">
<h4 class="fw-normal">Resources</h4> <h4 class="fw-normal">Resources</h4>
<ul class="list-unstyled"> <ul class="list-unstyled">
<li><a href="//odin-lang.org/docs" class="link-light">Docs</a></li> <li><a href="https://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/news" class="link-light">Blog</a></li>
</ul> </ul>
</nav> </nav>
<nav class="col-md-auto"> <nav class="col-md-auto">
@@ -39,5 +39,6 @@
</div> </div>
</footer> </footer>
<script src="//odin-lang.org/lib/bootstrap/js/bootstrap.min.js"></script> <script src="https://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/js/script.js"></script>
<script>hljs.highlightAll()</script>
tools/odin-html-docs/header.txt.html
+1 -29
View File
@@ -3,32 +3,4 @@
<head> <head>
<meta charset="utf-8"> <meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="viewport" content="width=device-width, initial-scale=1">
<title>{0:s}</title> <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">
tools/odin-html-docs/odin_html_docs_main.odin
+153 -53
View File
@@ -9,6 +9,7 @@ import "core:path/slashpath"
import "core:sort" import "core:sort"
import "core:slice" 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" GITHUB_CORE_URL :: "https://github.com/odin-lang/Odin/tree/master/core"
BASE_CORE_URL :: "/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) { write_html_header :: proc(w: io.Writer, title: string) {
fmt.wprintf(w, string(#load("header.txt.html")), title) 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) { 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) { write_core_directory :: proc(w: io.Writer) {
root := generate_directory_tree() root := generate_directory_tree()
fmt.wprintln(w, `<div class="row odin-main">`) fmt.wprintln(w, `<div class="row odin-main">`)
defer fmt.wprintln(w, `</div>`) 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">`) fmt.wprintln(w, `<article class="col-lg-12 p-4">`)
defer fmt.wprintln(w, `</article>`) defer fmt.wprintln(w, `</article>`)
fmt.wprintln(w, "<article>")
fmt.wprintln(w, "<header>") 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, "</header>")
fmt.wprintln(w, "</article>")
fmt.wprintln(w, "<div>") fmt.wprintln(w, "<div>")
fmt.wprintln(w, "\t<table class=\"doc-directory mt-4 mb-4\">") 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 == "" { if docs == "" {
return return
} }
it := docs Block_Kind :: enum {
was_code := true Paragraph,
was_paragraph := true Code,
prev_line: string }
for line in strings.split_iterator(&it, "\n") { Block :: struct {
text := strings.trim_space(line) kind: Block_Kind,
defer prev_line = line lines: []string,
}
if strings.has_prefix(line, "\t") { lines: [dynamic]string
if !was_code { it := docs
was_code = true; for line_ in strings.split_iterator(&it, "\n") {
if prev_line == "Example:" { line := strings.trim_right_space(line_)
fmt.wprint(w, `<pre class="doc-code doc-code-example"><code>`) append(&lines, line)
} else { }
fmt.wprint(w, `<pre class="doc-code"><code>`)
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")) case .Code:
continue if text == "" || strings.has_prefix(line, "\t") {
} else if was_code {
if text == "" {
continue continue
} }
was_code = false
fmt.wprintln(w, "</code></pre>")
}
if text == "" {
if was_paragraph { if i-start > 0 {
was_paragraph = false append(&blocks, Block{curr_block_kind, lines[start:i]})
fmt.wprintln(w, "</p>")
} }
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 continue
} }
if !was_paragraph { prev_line := ""
fmt.wprintln(w, "<p>") 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 lines := block.lines[:]
write_doc_line(w, text)
io.write_byte(w, '\n') end_line := block.lines[len(lines)-1]
} if block.kind == .Paragraph && i+1 < len(blocks) {
if was_code { if strings.has_prefix(end_line, "Example:") && blocks[i+1].kind == .Code {
// assert(!was_paragraph, str(pkg.name)) lines = lines[:len(lines)-1]
was_code = false }
fmt.wprintln(w, "</code></pre>") }
}
if was_paragraph { switch block.kind {
fmt.wprintln(w, "</p>") 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">`) fmt.wprintln(w, `<div class="row odin-main">`)
defer fmt.wprintln(w, `</div>`) 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 { // breadcrumbs
fmt.wprintln(w, `<div class="row">`) 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, `<h2>Index</h2>`)
fmt.wprintln(w, `<section class="doc-index" id="pkg-index">`) fmt.wprintln(w, `<div 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">`)
pkg_procs: [dynamic]^doc.Entity pkg_procs: [dynamic]^doc.Entity
pkg_proc_groups: [dynamic]^doc.Entity pkg_proc_groups: [dynamic]^doc.Entity
pkg_types: [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) slice.sort_by_key(pkg_consts[:], entity_key)
write_index :: proc(w: io.Writer, name: string, entities: []^doc.Entity) { write_index :: proc(w: io.Writer, name: string, entities: []^doc.Entity) {
fmt.wprintf(w, "<h3>%s</h3>\n", name) fmt.wprintln(w, `<div>`)
fmt.wprintln(w, `<section class="doc-index">`) 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 { if len(entities) == 0 {
io.write_string(w, "<p>This section is empty.</p>\n") io.write_string(w, "<p>This section is empty.</p>\n")
} else { } else {
@@ -956,7 +1047,6 @@ write_pkg :: proc(w: io.Writer, path: string, pkg: ^doc.Pkg) {
} }
fmt.wprintln(w, "</ul>") fmt.wprintln(w, "</ul>")
} }
fmt.wprintln(w, "</section>")
} }
entity_ordering := [?]struct{name: string, entities: []^doc.Entity} { 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) write_index(w, eo.name, eo.entities)
} }
fmt.wprintln(w, "</section>") fmt.wprintln(w, "</div>")
write_entity :: proc(w: io.Writer, e: ^doc.Entity) { 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, "<div class=\"doc-source\"><a href=\"{0:s}\"><em>Source</em></a></div>", src_url)
} }
fmt.wprintf(w, "</h3>\n") fmt.wprintf(w, "</h3>\n")
fmt.wprintln(w, `<div>`)
switch e.kind { switch e.kind {
case .Invalid, .Import_Name, .Library_Name: 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) init_string := str(e.init_string)
if init_string != "" { if init_string != "" {
io.write_string(w, " = ") io.write_string(w, " = ")
io.write_string(w, init_string) io.write_string(w, "…")
} }
fmt.wprintln(w, "</pre>") 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, "</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) { write_entities :: proc(w: io.Writer, title: string, entities: []^doc.Entity) {
fmt.wprintf(w, "<h2 id=\"pkg-{0:s}\">{0:s}</h2>\n", title) 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") io.write_string(w, "<p>This section is empty.</p>\n")
} else { } else {
for e in entities { for e in entities {
fmt.wprintln(w, `<div class="pkg-entity">`)
write_entity(w, e) write_entity(w, e)
fmt.wprintln(w, `</div>`)
} }
} }
fmt.wprintln(w, "</section>") fmt.wprintln(w, "</section>")
tools/odin-html-docs/style.css
+41 -15
View File
@@ -25,10 +25,6 @@ table.`directory {
padding-right: 0; padding-right: 0;
} }
.doc-directory tr[aria-controls]:hover {
background-color: #eee;
}
.doc-directory tr[aria-expanded=true] td.pkg-name:before { .doc-directory tr[aria-expanded=true] td.pkg-name:before {
content: "\2193"; content: "\2193";
} }
@@ -57,12 +53,12 @@ pre.doc-code {
pre.doc-code a { pre.doc-code a {
font-family: Consolas,Liberation Mono,Menlo,monospace!important; font-family: Consolas,Liberation Mono,Menlo,monospace!important;
text-decoration: none; text-decoration: none;
/*font-weight: bold;*/ color: #2179d8;
color: #00bfd5; font-weight: 800;
} }
pre.doc-code a.code-procedure { pre.doc-code a.code-procedure {
color: #079300; color: #047919;
} }
.pkg-line-doc { .pkg-line-doc {
@@ -90,18 +86,48 @@ a > .a-hidden {
a:hover > .a-hidden { a:hover > .a-hidden {
opacity: 100; opacity: 100;
} }
article.documentation h2 {
border-bottom: 1px dashed #c6c8ca;
padding-bottom: 0.5rem;
}
section.documentation h3 { section.documentation h3 {
font-size: calc(1.1rem + .2vw); font-size: calc(1.1rem + .2vw);
} }
.pkg-index h3 {
margin-top: 0 !important;
padding-top: 0 !important;
}
.doc-index h3 { .documentation .pkg-entity {
border-bottom: 1px solid #c6c8ca; padding-bottom: 0.75rem;
padding-bottom: 0.25rem; 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;
} }