From 55dc0efdefbb5c5de5f9c181a6b37a706836f10a Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Sun, 29 Dec 2024 16:28:53 +0100 Subject: [PATCH 1/4] docs: docgen proto with `protoc-gen-doc` Signed-off-by: Jan Kowalleck --- .github/workflows/build_docs.yml | 18 +++++++++++++++ docgen/proto/.gitignore | 1 + docgen/proto/gen.sh | 39 ++++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 docgen/proto/.gitignore create mode 100755 docgen/proto/gen.sh diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 2d0b41e9..492a8e9d 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -59,3 +59,21 @@ jobs: name: JSON-Schema-documentation path: docgen/json/docs if-no-files-found: error + docs_proto: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docgen/proto + steps: + - name: Checkout + # see https://github.com/actions/checkout + uses: actions/checkout@v4 + - name: Generate Schema documentation + run: ./gen.sh + - name: Archive Schema documentation + # https://github.com/actions/upload-artifact + uses: actions/upload-artifact@v4 + with: + name: PROTO-Schema-documentation + path: docgen/proto/docs + if-no-files-found: error diff --git a/docgen/proto/.gitignore b/docgen/proto/.gitignore new file mode 100644 index 00000000..6e684992 --- /dev/null +++ b/docgen/proto/.gitignore @@ -0,0 +1 @@ +/docs/ diff --git a/docgen/proto/gen.sh b/docgen/proto/gen.sh new file mode 100755 index 00000000..1e940c1c --- /dev/null +++ b/docgen/proto/gen.sh @@ -0,0 +1,39 @@ +#!/bin/bash +set -eu + +THIS_PATH="$(realpath "$(dirname "$0")")" +SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")" +DOCS_PATH="$THIS_PATH/docs" +TEMPLATES_PATH="$THIS_PATH/templates" + +PROTOC_GEN_DOC_VERSION='1.5.1' + +# -- + +rm -f -R "$DOCS_PATH" +mkdir -p "$DOCS_PATH/"{1.3,1.4,1.5,1.6} + +generate () { + version="$1" + + ## docs: https://github.com/pseudomuto/protoc-gen-doc + docker run --rm \ + -v "${DOCS_PATH}/${version}:/out" \ + -v "${SCHEMA_PATH}:/protos:ro" \ + -v "${TEMPLATES_PATH}:/templates:ro" \ + "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \ + --doc_opt=html,index.html \ + "bom-${version}.proto" + + # fix file permissions + docker run --rm \ + -v "${DOCS_PATH}/${version}:/out" \ + --entrypoint chown \ + "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \ + "$(id -g):$(id -u)" -R /out +} + +generate 1.3 +generate 1.4 +generate 1.5 +generate 1.6 From 505dd402c623630215a2b03101f82cc8dfcd84ce Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Thu, 2 Jan 2025 10:15:00 +0100 Subject: [PATCH 2/4] prep theme Signed-off-by: Jan Kowalleck --- docgen/proto/gen.sh | 2 + docgen/proto/templates/html.tmpl | 441 +++++++++++++++++++++++++++++++ 2 files changed, 443 insertions(+) create mode 100644 docgen/proto/templates/html.tmpl diff --git a/docgen/proto/gen.sh b/docgen/proto/gen.sh index 1e940c1c..bbbe1380 100755 --- a/docgen/proto/gen.sh +++ b/docgen/proto/gen.sh @@ -15,6 +15,8 @@ mkdir -p "$DOCS_PATH/"{1.3,1.4,1.5,1.6} generate () { version="$1" + title="CycloneDX v$version Proto Reference" + echo "Generating: $title" ## docs: https://github.com/pseudomuto/protoc-gen-doc docker run --rm \ diff --git a/docgen/proto/templates/html.tmpl b/docgen/proto/templates/html.tmpl new file mode 100644 index 00000000..570c1fbb --- /dev/null +++ b/docgen/proto/templates/html.tmpl @@ -0,0 +1,441 @@ + +{{!-- + +template taken from +https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl + +--}} + + + Protocol Documentation + + + + + + + + + + +

Protocol Documentation

+ +

Table of Contents

+ +
+ +
+ + {{range .Files}} + {{$file_name := .Name}} +
+

{{.Name}}

Top +
+ {{p .Description}} + + {{range .Messages}} +

{{.LongName}}

+ {{p .Description}} + + {{if .HasFields}} + + + + + + {{range .Fields}} + + + + + + + {{end}} + +
FieldTypeLabelDescription
{{.Name}}{{.LongType}}{{.Label}}

{{if (index .Options "deprecated"|default false)}}Deprecated. {{end}}{{.Description}} {{if .DefaultValue}}Default: {{.DefaultValue}}{{end}}

+ + {{$message := .}} + {{- range .FieldOptions}} + {{$option := .}} + {{if eq . "validator.field" "validate.rules" }} +

Validated Fields

+ + + + + + + + + {{range $message.FieldsWithOption .}} + + + + + {{end}} + +
FieldValidations
{{.Name}} +
    + {{range (.Option $option).Rules}} +
  • {{.Name}}: {{.Value}}
    • + {{end}} +
+
+ {{else}} +

Fields with {{.}} option

+ + + + + + + + + {{range $message.FieldsWithOption .}} + + + + + {{end}} + +
NameOption
{{.Name}}

{{ printf "%+v" (.Option $option)}}

+ {{end}} + {{end -}} + {{end}} + + {{if .HasExtensions}} +
+ + + + + + {{range .Extensions}} + + + + + + + + {{end}} + +
ExtensionTypeBaseNumberDescription
{{.Name}}{{.LongType}}{{.ContainingLongType}}{{.Number}}

{{.Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}}

+ {{end}} + {{end}} + + {{range .Enums}} +

{{.LongName}}

+ {{p .Description}} + + + + + + {{range .Values}} + + + + + + {{end}} + +
NameNumberDescription
{{.Name}}{{.Number}}

{{.Description}}

+ {{end}} + + {{if .HasExtensions}} +

File-level Extensions

+ + + + + + {{range .Extensions}} + + + + + + + + {{end}} + +
ExtensionTypeBaseNumberDescription
{{.Name}}{{.LongType}}{{.ContainingLongType}}{{.Number}}

{{.Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}}

+ {{end}} + + {{range .Services}} +

{{.Name}}

+ {{p .Description}} + + + + + + {{range .Methods}} + + + + + + + {{end}} + +
Method NameRequest TypeResponse TypeDescription
{{.Name}}{{.RequestLongType}}{{if .RequestStreaming}} stream{{end}}{{.ResponseLongType}}{{if .ResponseStreaming}} stream{{end}}

{{.Description}}

+ + {{$service := .}} + {{- range .MethodOptions}} + {{$option := .}} + {{if eq . "google.api.http"}} +

Methods with HTTP bindings

+ + + + + + + + + + + {{range $service.MethodsWithOption .}} + {{$name := .Name}} + {{range (.Option $option).Rules}} + + + + + + + {{end}} + {{end}} + +
Method NameMethodPatternBody
{{$name}}{{.Method}}{{.Pattern}}{{.Body}}
+ {{else}} +

Methods with {{.}} option

+ + + + + + + + + {{range $service.MethodsWithOption .}} + + + + + {{end}} + +
Method NameOption
{{.Name}}

{{ printf "%+v" (.Option $option)}}

+ {{end}} + {{end -}} + {{end}} + {{end}} + +

Scalar Value Types

+ + + + + + {{range .Scalars}} + + + + + + + + + + + + {{end}} + +
.proto TypeNotesC++JavaPythonGoC#PHPRuby
{{.ProtoType}}{{.Notes}}{{.CppType}}{{.JavaType}}{{.PythonType}}{{.GoType}}{{.CSharp}}{{.PhpType}}{{.RubyType}}
+ + From a9e11e8c868b3de12bf1b870bfebf996d804c5c8 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Thu, 2 Jan 2025 10:20:47 +0100 Subject: [PATCH 3/4] prep theme Signed-off-by: Jan Kowalleck --- docgen/proto/gen.sh | 2 +- docgen/proto/templates/html.tmpl | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docgen/proto/gen.sh b/docgen/proto/gen.sh index bbbe1380..9ddd0ec1 100755 --- a/docgen/proto/gen.sh +++ b/docgen/proto/gen.sh @@ -24,7 +24,7 @@ generate () { -v "${SCHEMA_PATH}:/protos:ro" \ -v "${TEMPLATES_PATH}:/templates:ro" \ "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \ - --doc_opt=html,index.html \ + --doc_opt=/templates/html.tmpl,index.html \ "bom-${version}.proto" # fix file permissions diff --git a/docgen/proto/templates/html.tmpl b/docgen/proto/templates/html.tmpl index 570c1fbb..fca1e303 100644 --- a/docgen/proto/templates/html.tmpl +++ b/docgen/proto/templates/html.tmpl @@ -1,10 +1,10 @@ -{{!-- +{{/* template taken from https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl ---}} +*/}} Protocol Documentation From 775ab7591d1f654342c6a51e82abc9de884fc1c3 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Sat, 11 Jan 2025 15:03:23 +0100 Subject: [PATCH 4/4] docs: docsgen resture output for website Signed-off-by: Jan Kowalleck --- docgen/proto/gen.sh | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docgen/proto/gen.sh b/docgen/proto/gen.sh index 9ddd0ec1..a4cf7c89 100755 --- a/docgen/proto/gen.sh +++ b/docgen/proto/gen.sh @@ -11,16 +11,18 @@ PROTOC_GEN_DOC_VERSION='1.5.1' # -- rm -f -R "$DOCS_PATH" -mkdir -p "$DOCS_PATH/"{1.3,1.4,1.5,1.6} generate () { version="$1" title="CycloneDX v$version Proto Reference" echo "Generating: $title" + OUT_DIR="$DOCS_PATH/$version/proto/" + mkdir -p "$OUT_DIR" + ## docs: https://github.com/pseudomuto/protoc-gen-doc docker run --rm \ - -v "${DOCS_PATH}/${version}:/out" \ + -v "${OUT_DIR}:/out" \ -v "${SCHEMA_PATH}:/protos:ro" \ -v "${TEMPLATES_PATH}:/templates:ro" \ "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \ @@ -29,7 +31,7 @@ generate () { # fix file permissions docker run --rm \ - -v "${DOCS_PATH}/${version}:/out" \ + -v "${OUT_DIR}:/out" \ --entrypoint chown \ "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \ "$(id -g):$(id -u)" -R /out