Skip to content

Commit

Permalink
Refactor documentation infrastructure
Browse files Browse the repository at this point in the history
  • Loading branch information
@chances
chances committed Feb 25, 2024
1 parent 7db6a93 commit dea209f
Show file tree
Hide file tree
Showing 10 changed files with 747 additions and 139 deletions.
22 changes: 2 additions & 20 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,29 +56,11 @@ cover: $(SOURCES)
# Documentation
#################################################

PACKAGE_VERSION := 0.4.0
docs/sitemap.xml: $(SOURCES)
dub build -b ddox
@echo "Performing cosmetic changes..."
# Navigation Sidebar
@$(SED) -i -e "/<nav id=\"main-nav\">/r views/nav.html" -e "/<nav id=\"main-nav\">/d" `find docs -name '*.html'`
# Page Titles
@$(SED) -i "s/<\/title>/ - wgpu-d<\/title>/" `find docs -name '*.html'`
# Index
@$(SED) -i "s/API documentation/API Reference/g" docs/index.html
@$(SED) -i -e "/<h1>API Reference<\/h1>/r views/index.html" -e "/<h1>API Reference<\/h1>/d" docs/index.html
# License Link
@$(SED) -i "s/3-Clause BSD License/<a href=\"https:\/\/opensource.org\/licenses\/BSD-3-Clause\">3-Clause BSD License<\/a>/" `find docs -name '*.html'`
# Footer
@$(SED) -i -e "/<p class=\"faint\">Generated using the DDOX documentation generator<\/p>/r views/footer.html" -e "/<p class=\"faint\">Generated using the DDOX documentation generator<\/p>/d" `find docs -name '*.html'`
# Dub Package Version
@echo Latest tag: `git describe --tags --abbrev=0`
@$(SED) -i "s/DUB_VERSION/$(PACKAGE_VERSION)/g" `find docs -name '*.html'`
@echo Done

docs: docs/sitemap.xml
ifeq ($(OS),Windows_NT)
$(error Build documentation on *nix!)
else
@dub build -b docs
endif
.PHONY: docs

Expand Down
27 changes: 27 additions & 0 deletions docs/process.d
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
/// Process handlebars templates in API documentation.
///
/// Authors: Chance Snow
/// Copyright: Copyright © 2024 Chance Snow. All rights reserved.
/// License: MIT License
module wgpu.docs.process;

import handlebars.tpl;
static import std.file;
import std.process;
import std.stdio;

void main(string[] args) {
string template_ = std.file.readText("views/index.hbs");

struct Constants {
string DUB_VERSION;
auto SYMBOLS = new string[0];
auto MODULES = new string[0];
}

auto gitTagCmd = execute(["git", "describe", "--tags", "--abbrev=0"]);
assert(gitTagCmd.status == 0);
gitTagCmd.output.writeln;
auto result = render(template_, Constants(gitTagCmd.output));
result.writeln;
}
338 changes: 338 additions & 0 deletions docs/styles/docs.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,338 @@
body {
margin: 0;
padding: 0;
font-family: "HelveticaNeue-Light", "Helvetica Neue Light", "Helvetica Neue",
"Segoe UI", "Roboto Sans", "Open Sans", sans-serif;
font-size: 10pt;
}

.flex {
display: flex;
}

.row {
flex-direction: row;
}

.column {
flex-direction: column;
}

h1, h2, h3 {
font-weight: normal;
}
h1 {
margin-top: -5pt;
}
h2 {
margin-top: 2em;
}
h3 {
margin-top: 1.5em;
}

a {
color: #1133EE;
text-decoration: none;
}
a:hover {
color: #4488FF;
text-decoration: underline;
}

table {
border-collapse: collapse;
}
th, td {
padding: 0 10pt;
vertical-align: top;
}
th:first-child,
td:first-child {
padding-left: 0;
}
th {
text-align: left;
font-weight: normal;
font-style: italic;
}
tr {
border-bottom: 1px dashed #ddd;
vertical-align: top;
}
col.caption {
min-width: 150pt;
}

p.faint {
color: #ccc;
}

span.tableEntryAnnotation {
color: #888;
}

main,
main > aside:first-of-type > nav,
#symbolSearch,
#symbolSearchResults {
box-sizing: border-box;
}

main {
display: flex;
vertical-align: top;
font-size: 9.5pt;
flex-grow: 1;
}

main > aside:first-of-type > nav {
vertical-align: top;
font-size: 9.5pt;
padding: 2em 1.5em;
min-width: 16em;
background: linear-gradient(#ddd, #fff),
linear-gradient(90deg, rgba(255, 255, 255, 1), rgba(255, 255, 255, 0)),
linear-gradient(#eee, #fff);
background-size:
1px 100%,
100% 100%,
100% 100%;
background-position:
100% 0,
0 0,
0 0;
background-repeat: no-repeat, no-repeat;
}

main > aside:first-of-type nav h1 {
align-self: center;
margin: 0 0 0 0.25rem;
font-size: 19px;
line-height: 1;
}

main > aside:first-of-type nav h1 > span {
display: block;
padding-bottom: 0.25em;
white-space: nowrap;
}
main > aside:first-of-type nav h1 > span.faint {
font-weight: lighter;
}

#logo {
margin-right: 0.5rem;
max-width: 4rem;
}

main > article {
margin: 2em;
}

article.module > section.members > ul {
padding: 0;
list-style: none;
}

ul li > dd.decl {
margin: 8px 0 0 12px;
}

ul li > dd.decl > ul.members {
list-style-type: square;
}

article.module > section.members > ul > li {
padding: 0;
}

ul.enum.members > li.member > dt.decl > code {
display: none;
}

dt.decl {
font-family: monospace;
}

#symbolSearchPane form {
margin-bottom: 1.5em;
}
#symbolSearch {
width: 100%;
}
#symbolSearchResults {
position: absolute;
padding-right: 0.5em;
margin: 0;
margin-top: -1.5em;
background: white;
min-width: 20em;
border: 1px solid #ddd;
box-shadow: 0px 5px 20px 0 rgba(0, 0, 0, 0.5);
}
.symbolList {
list-style: none;
padding: 0;
overflow: hidden;
}
.symbolList li {
background-repeat: no-repeat;
background-position: 0 1pt;
padding-left: 18px;
}

.searchResults.symbolList li {
background-position: 0 5pt;
}
.searchResults h2 {
margin-bottom: 0;
margin-top: 1em;
}

.symbolList .deprecated a {
color: gray;
}
.symbolList .module {
background-image: url(../icons/module.png);
}
.symbolList .functiondeclaration {
background-image: url(../icons/function.png);
}
.symbolList .classdeclaration {
background-image: url(../icons/class.png);
}
.symbolList .interfacedeclaration {
background-image: url(../icons/interface.png);
}
.symbolList .structdeclaration {
background-image: url(../icons/struct.png);
}
.symbolList .variabledeclaration {
background-image: url(../icons/variable.png);
}
.symbolList .property {
background-image: url(../icons/property.png);
}
.symbolList .enumdeclaration {
background-image: url(../icons/enum.png);
}
.symbolList .enummemberdeclaration {
background-image: url(../icons/enummember.png);
}
.symbolList .aliasdeclaration {
background-image: url(../icons/alias.png);
}
.symbolList .templatedeclaration {
background-image: url(../icons/template.png);
}

ul.tree-view li {
list-style-type: none;
padding-left: 18px;
padding-right: 4px;
}

ul.tree-view .package {
padding-left: 18px;
background-image: url(../icons/package.png);
background-repeat: no-repeat;
background-position: left 2px;
cursor: default;
}

ul.tree-view .package:hover {
box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.1);
}

ul.tree-view .module {
padding-left: 18px;
background-image: linear-gradient(
rgba(255, 255, 255, 0.5),
rgba(255, 255, 255, 0.5)
),
url(../icons/module.png);
background-repeat: no-repeat, no-repeat;
background-position:
left 1px,
left 1px;
background-size: 18px 16px;
}

ul.tree-view .module.selected,
ul.tree-view .package.selected {
font-weight: bold;
}
ul.tree-view .module.selected {
background-image: url(../icons/module.png);
}

ul.tree-view li.collapsed ul {
display: none;
}

ul.tree-view {
padding: 0;
margin: 0;
}

ul.tree-view ul {
margin: 0;
padding: 0;
}

a.protected {
font-style: italic;
background-image: url(../icons/protected.png);
background-repeat: no-repeat;
padding-left: 16px;
}
a.package {
font-style: italic;
background-image: url(../icons/package.png);
background-repeat: no-repeat;
padding-left: 16px;
}

a.private {
font-style: italic;
background-image: url(../icons/private.png);
background-repeat: no-repeat;
padding-left: 16px;
}
a.inherited:after {
content: url(../icons/inherited.png);
padding-left: 2pt;
}

nav.page-nav ul {
list-style: none;
padding-left: 0;
}
nav.page-nav li a {
color: black;
}
nav.page-nav li:before {
content: "▼";
padding-right: 3px;
}

.license-info {
margin-top: 2em;
color: #888;
}
.license-info p {
display: inline;
}

footer {
display: flex;
justify-content: space-between;
margin: 0 2em 2em;
}

@media (max-width: 500pt) {
body {
display: block;
}
}
Loading

0 comments on commit dea209f

Please sign in to comment.