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..a4cf7c89 --- /dev/null +++ b/docgen/proto/gen.sh @@ -0,0 +1,43 @@ +#!/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" + +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 "${OUT_DIR}:/out" \ + -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 \ + "bom-${version}.proto" + + # fix file permissions + docker run --rm \ + -v "${OUT_DIR}:/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 diff --git a/docgen/proto/templates/html.tmpl b/docgen/proto/templates/html.tmpl new file mode 100644 index 00000000..fca1e303 --- /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}}
+ +