feat: Publish documentation on each release

Publish simple generated documentation on each release. The docs are
a bit sparse right now, but we can use markdown in comment blocks for
messages/services to improve the documentation.

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: sabledocs build
+
+on:
+  push:
+    branches:
+      - release/**
+
+jobs:
+  docs:
+    name: Sphinx
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+
+      - name: Build docs
+        run: |
+          pip install virtualenv
+          make docs
+
+      - uses: peaceiris/[email protected]
+        name: Publish to GitHub Pages
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build
+          force_orphan: true
+
+      - name: Archive Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/build

.gitignore

@@ -145,9 +145,12 @@ data/
 /gocd/templates/vendor/
 /gocd/generated-pipelines/
 
-
 # Codecov
 .artifacts/
 
 # Generated bindings
-py/sentry_protos/*
+/py/sentry_protos/*
+
+# Generated documentation
+/docs/build/*
+/docs/descriptor.pb

Makefile

@@ -52,3 +52,10 @@ update-vendor:
 
 .PHONY: build
 build: build-py build-rust
+
+
+.PHONY: docs
+docs:
+	pip install sabledocs
+	protoc ./proto/sentry_protos/*/*/*.proto -I ./proto/ -o ./docs/descriptor.pb --include_source_info
+	cd docs && sabledocs

docs/sabledocs.toml

@@ -0,0 +1,60 @@
+# Configures the main title of the documentation site.
+module-title = "Sentry Protos"
+
+# Specifies the name of the Protobuf descriptor file.
+# Default value: "descriptor.pb"
+input-descriptor-file = "descriptor.pb"
+
+# Specifies the file which contains the content to display on the main page above the package list.
+# Default value: ""
+# main-page-content-file = "intro.md"
+
+# The output folder to which the documentation is generated.
+# Default value: "sabledocs_output"
+output-dir = "build"
+
+# Controls whether the the search functionality is enabled with a prebuilt Lunr index.
+# Default value: true
+enable-lunr-search = true
+
+# Copyright message displayed in the footer.
+# Default value: ""
+footer-content = "© 2024 Functional Software. All rights reserved."
+
+# The following 3 fields configure the source control repository of the project.
+# They are used to generate deeplinks for the members of the Proto model pointing to the original source
+# code. By default these fields are not configured, and source code links are not included in the docs.
+# The repository-type field supports two possible values, "github" and "bitbucket".
+# The fields repository-url and repository-branch should be configured to point to the correct repository.
+# repository-dir should be set only if the root of your Protobuf module is in a specific directory inside your repository.
+repository-type = "github"
+repository-url = "https://github.com/getsentry/sentry-protos"
+repository-branch = "main"
+repository-dir = "proto"
+
+# In each comment, ignore everything that comes after (until end of the comment) one of the keywords.
+# Default value: []
+ignore-comments-after = ["@exclude"]
+# In each comment, ignore all lines that contain at least one keyword from the following list.
+# Default value: []
+ignore-comment-lines-containing = ["buf:lint"]
+
+# Packages can be hidden from the generated documentation by adding them to the hidden-packages
+# collection. In the templates, the field non_hidden_packages can be used to access the packages which are
+# not listed in hidden-packages. (And the packages field returns all packages.)
+# Default value: []
+hidden-packages = ["google.protobuf"]
+
+# By default, packages and members in a package are ordered alphabetically.
+# By setting the member-ordering option to "preserve", the original order present in the Protobuf
+# definitions will be preserved.
+# When using the "preserve" option and having multiple proto input files, the order of the members will
+# depend not just on the physical order in the Protobuf files, but also on the order in which the files
+# were listed in the input when `protoc` was executed.
+# Default value: ""
+member-ordering = "preserve"
+
+# The markdown extensions supported by the main-page-content-file
+# Default value: ["fenced_code"]
+# See: https://python-markdown.github.io/extensions/#officially-supported-extensions
+markdown-extensions = ["fenced_code", "nl2br"]