Skip to content

Commit

Permalink
docs: docsgen theme and linkd for proto (#571)
Browse files Browse the repository at this point in the history 
theme for #557

---------

Signed-off-by: Jan Kowalleck <[email protected]>
  • Loading branch information
@jkowalleck
jkowalleck authored Jan 11, 2025
1 parent 08499f3 commit a43e6f7
Show file tree
Hide file tree
Showing 4 changed files with 163 additions and 19 deletions.
5 changes: 5 additions & 0 deletions docgen/json/templates/cyclonedx/base.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@
<li><a class="dropdown-item" href="/docs/1.2/xml/">v1.2 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.1/xml/">v1.1 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.0/xml/">v1.0 (XML)</a></li>
<li><hr class="dropdown-divider"/></li>
<li><a class="dropdown-item" href="/docs/1.6/proto/">v1.6 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.5/proto/">v1.5 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.4/proto/">v1.4 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.3/proto/">v1.3 (Protobuf)</a></li>
</ul>
</li>
</ul>
Expand Down
11 changes: 8 additions & 3 deletions docgen/proto/gen.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,11 @@ rm -f -R "$DOCS_PATH"

generate () {
version="$1"
title="CycloneDX v$version Proto Reference"
title="CycloneDX v$version Protobuf Reference"
echo "Generating: $title"

OUT_DIR="$DOCS_PATH/$version/proto/"
OUT_DIR="$DOCS_PATH/$version/proto"
OUT_FILE="index.html"
mkdir -p "$OUT_DIR"

## docs: https://github.com/pseudomuto/protoc-gen-doc
Expand All @@ -26,7 +27,7 @@ generate () {
-v "${SCHEMA_PATH}:/protos:ro" \
-v "${TEMPLATES_PATH}:/templates:ro" \
"pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
--doc_opt=/templates/html.tmpl,index.html \
--doc_opt=/templates/html.tmpl,"$OUT_FILE" \
"bom-${version}.proto"

# fix file permissions
Expand All @@ -35,6 +36,10 @@ generate () {
--entrypoint chown \
"pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
"$(id -u):$(id -g)" -R /out

sed -i -e "s/\${quotedTitle}/\"$title\"/g" "$OUT_DIR/$OUT_FILE"
sed -i -e "s/\${title}/$title/g" "$OUT_DIR/$OUT_FILE"
sed -i -e "s/\${version}/$version/g" "$OUT_DIR/$OUT_FILE"
}

generate 1.3
Expand Down
161 changes: 145 additions & 16 deletions docgen/proto/templates/html.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,31 @@ https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl
*/}}
<html>
<head>
<title>Protocol Documentation</title>
<meta charset="UTF-8">
<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Ubuntu:400,700,400italic"/>
<title>${title}</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta charset="UTF-8"/>
<meta name="twitter:card" content="summary_large_image"/>
<meta name="twitter:site" content="@CycloneDX_Spec"/>
<meta name="twitter:title" content="${quotedTitle}"/>
<meta name="twitter:image" content="https://cyclonedx.org/images/CycloneDX-Social-Card.png"/>
<meta name="twitter:description" content="${quotedTitle}"/>
<meta name="description" content="${quotedTitle}"/>
<meta property="og:description" content="${quotedTitle}"/>
<meta property="og:title" content="${quotedTitle}"/>
<meta property="og:locale" content="en_US"/>
<meta property="og:type" content="website" />
<meta property="og:image" content="https://cyclonedx.org/images/CycloneDX-Social-Card.png" />
<link href="/favicon.ico" rel="shortcut icon" type="image/ico" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/css/bootstrap.min.css" integrity="sha512-rt/SrQ4UNIaGfDyEXZtNcyWvQeOq0QLygHluFQcSjaGB04IxWhal71tKuzP6K8eYXYB6vJV4pHkXcmFGGQ1/0w==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" integrity="sha512-SfTiTlX6kk+qitfevl/7LibUOeJWlt9rbyDn92a1DqWOw9vWG2MFoays0sgObmWazO5BQPiFucnnEAjpAB+/Sw==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<link rel="stylesheet" type="text/css" href="schema_doc.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.slim.js" integrity="sha512-docBEeq28CCaXCXN7cINkyQs0pRszdQsVBFWUd+pLNlEk3LDlSDDtN7i1H+nTB8tshJPQHS0yu0GW9YGFd/CRg==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/js/bootstrap.min.js" integrity="sha512-7rusk8kGPFynZWu26OKbTeI+QPoYchtxsmPeBqkHIEXJxeun4yJ4ISYe7C6sz9wdxeE1Gk3VxsIWgCZTc+vX3g==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/markdown-it/13.0.2/markdown-it.min.js" integrity="sha512-ohlWmsCxOu0bph1om5eDL0jm/83eH09fvqLDhiEdiqfDeJbEvz4FSbeY0gLJSVJwQAp0laRhTXbUQG+ZUuifUQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="schema_doc.min.js"></script>
<style>
body {
width: 60em;
margin: 1em auto;
color: #222;
font-family: "Ubuntu", sans-serif;
padding-bottom: 4em;
}
/* template-originals */
body { /* removed */ }

h1 {
font-weight: normal;
Expand Down Expand Up @@ -164,23 +178,135 @@ https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl
border-radius: 1ex;
}
</style>

<!-- User custom CSS -->
<link rel="stylesheet" type="text/css" href="stylesheet.css"/>
<style>
/* customs */
body {
font: 16px/1.5em "Helvetica Neue",Helvetica,Arial,sans-serif;
color: #222;
margin: 0;
padding: 0;
}
.navbar {
height: 90px;
padding: 0;
}
.navbar-inverse .navbar-nav>.open>a,
.navbar-inverse .navbar-nav>.open>a:focus,
.navbar-inverse .navbar-nav>.open>a:hover,
.navbar-inverse {
background-image: linear-gradient(269.12deg, rgba(232, 52, 82, 1) 0%, rgba(136, 38, 125, 1) 51.26%, rgba(52, 57, 175, 1) 100%);
}
.navbar-brand, .navbar-fixed-top {
padding: 0 30px 0 30px;
}
.navbar-inverse .navbar-nav>li>a {
color: #ffffff;
}
.site-header__logo img {
height: 90px;
}
.version-selector {
font-size: 1.2rem
}
.table .thead-dark th {
background-color: #323550;
}
.container {
margin-right: auto;
margin-left: auto;
padding-left: 15px;
padding-right: 15px;
}
.container-fluid {
padding: 30px 30px;
}
.nav-sub-item > a {
padding-left: 30px !important;
}
ul .dropdown-menu li {
padding-top: 0;
padding-bottom: 0;
}
.dropdown-toggle:after {
border-left: 8px solid transparent;
border-right: 8px solid transparent;
border-top: 8px solid #ffffff;
margin-left: 10px;
vertical-align: middle;
}
h1, h2, h3, h4, h5, h6 {
color: rgb(52 57 175);

}
h1 {
font-size: 36px;
}
h3 {
padding-top: 2ex;
}
pre {
padding: 5px;
}
a {
color: #2157c4;
}
.badge {
color:#4273d6;
background-color: #c8ddf0;
}
</style>
</head>

<body>

<h1 id="title">Protocol Documentation</h1>
<nav class="navbar fixed-top navbar-expand-sm navbar-inverse">
<a href="/" class="navbar-brand site-header__logo"><img src="https://cyclonedx.org/images/logo-all-white.svg" height="48" width="276"></img></a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarScroll" aria-controls="navbarScroll" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarScroll">
<ul class="navbar-nav mr-auto my-2 my-lg-0 navbar-nav-scroll" style="max-height: 100px;">
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarScrollingDropdown" role="button" data-toggle="dropdown" aria-expanded="false">
v${version} (Protobuf)
</a>
<ul class="dropdown-menu" aria-labelledby="navbarScrollingDropdown">
<li><a class="dropdown-item" href="/docs/1.6/json/">v1.6 (JSON)</a></li>
<li><a class="dropdown-item" href="/docs/1.5/json/">v1.5 (JSON)</a></li>
<li><a class="dropdown-item" href="/docs/1.4/json/">v1.4 (JSON)</a></li>
<li><a class="dropdown-item" href="/docs/1.3/json/">v1.3 (JSON)</a></li>
<li><a class="dropdown-item" href="/docs/1.2/json/">v1.2 (JSON)</a></li>
<li><hr class="dropdown-divider"/></li>
<li><a class="dropdown-item" href="/docs/1.6/xml/">v1.6 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.5/xml/">v1.5 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.4/xml/">v1.4 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.3/xml/">v1.3 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.2/xml/">v1.2 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.1/xml/">v1.1 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.0/xml/">v1.0 (XML)</a></li>
<li><hr class="dropdown-divider"/></li>
<li><a class="dropdown-item" href="/docs/1.6/proto/">v1.6 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.5/proto/">v1.5 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.4/proto/">v1.4 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.3/proto/">v1.3 (Protobuf)</a></li>
</ul>
</li>
</ul>
</div>
</nav>
<div class="container-fluid" style="margin-top:110px; margin-bottom:3rem">

<h1 id="title">${title}</h1>

<h2>Table of Contents</h2>

<div id="toc-container">
<ul id="toc">
{{range .Files}}
{{$file_name := .Name}}
{{$file_package := .Package}}
<li>
<a href="#{{.Name}}">{{.Name}}</a>
<a href="#{{.Package}}">Package: {{.Package}}</a>
<ul>
{{range .Messages}}
<li>
Expand Down Expand Up @@ -211,8 +337,9 @@ https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl

{{range .Files}}
{{$file_name := .Name}}
{{$file_package := .Package}}
<div class="file-heading">
<h2 id="{{.Name}}">{{.Name}}</h2><a href="#title">Top</a>
<h2 id="{{.Package}}">Package: {{.Package}}</h2><a href="#title">Top</a>
</div>
{{p .Description}}

Expand Down Expand Up @@ -437,5 +564,7 @@ https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl
{{end}}
</tbody>
</table>

</div>
</body>
</html>
5 changes: 5 additions & 0 deletions docgen/xml/xs3p.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,11 @@
<li><a class="dropdown-item" href="/docs/1.2/xml/">v1.2 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.1/xml/">v1.1 (XML)</a></li>
<li><a class="dropdown-item" href="/docs/1.0/xml/">v1.0 (XML)</a></li>
<li style="padding:0"><hr class="dropdown-divider"/></li>
<li><a class="dropdown-item" href="/docs/1.6/proto/">v1.6 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.5/proto/">v1.5 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.4/proto/">v1.4 (Protobuf)</a></li>
<li><a class="dropdown-item" href="/docs/1.3/proto/">v1.3 (Protobuf)</a></li>
</ul>
</li>
</ul>
Expand Down

0 comments on commit a43e6f7

Please sign in to comment.