Merge pull request #3 from pseudomuto/master

Update

.github/workflows/release.yaml

@@ -29,3 +29,18 @@ jobs:
           args: release --rm-dist
         env:
           GITHUB_TOKEN: ${{ secrets.GH_RELEASE_TOKEN }}
+      - name: Set up Java
+        uses: actions/setup-java@v2
+        with:
+          java-version: '11'
+          distribution: 'adopt'
+      - name: Publish package
+        uses: gradle/gradle-build-action@v2
+        with:
+          gradle-version: 7.4
+          arguments: publish
+        env:
+          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
+          ORG_GRADLE_PROJECT_signingKey: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGKEY }}
+          ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGPASSWORD }}

.gitignore

@@ -1,4 +1,6 @@
+/.gradle
 /bin
+/build
 /coverage.txt
 /dist
 /tmp/

CONTRIBUTING.md

@@ -76,3 +76,9 @@ From an up-to-date master, do the following:
 1. `git push origin master --tags`.
 
 Once the tag is on GitHub, the release action will handle pushing to docker and creating a release in GitHub.
+
+### Publish the Maven artifacts
+
+1. Head over to https://s01.oss.sonatype.org/#stagingRepositories
+1. Verify the contents of the staging repo and close it
+1. After successful closing (test suite is run), release the repo

README.md

@@ -21,6 +21,9 @@ If you'd like to install this locally, you can `go get` it.
 
 Alternatively, you can download a pre-built release for your platform from the [releases][] page.
 
+Finally, this plugin is also available on Maven Central. For details about how to use it, check out the [gradle
+example](examples/gradle).
+
 ## Invoking the Plugin
 
 The plugin is invoked by passing the `--doc_out`, and `--doc_opt` options to the `protoc` compiler. The option has the

build.gradle

@@ -0,0 +1,113 @@
+plugins {
+  id 'maven-publish'
+  id 'signing'
+}
+
+group = 'io.github.pseudomuto'
+
+publishing {
+  publications {
+    maven(MavenPublication) {
+      groupId = 'io.github.pseudomuto'
+      artifactId = rootProject.name
+      version = System.getenv("GITHUB_REF_NAME")
+      // Strip "v" from version number
+      if (version.startsWith("v")) {
+        version = version.substring(1)
+      }
+
+      pom {
+        name = groupId + ':' + rootProject.name
+        description = 'This is a documentation generator plugin for the Google Protocol Buffers compiler (protoc). The plugin can generate HTML, JSON, DocBook, and Markdown documentation from comments in your .proto files.'
+        url = 'https://github.com/pseudomuto/protoc-gen-doc'
+        licenses {
+          license {
+            name = 'MIT License'
+            url = 'https://github.com/pseudomuto/protoc-gen-doc/blob/master/LICENSE.md'
+          }
+        }
+        developers {
+          developer {
+            id = 'pseudomuto'
+            name = 'David Muto'
+            email = '[email protected]'
+          }
+        }
+        scm {
+          connection = 'scm:git:[email protected]:pseudomuto/protoc-gen-doc.git'
+          developerConnection = 'scm:git:[email protected]:pseudomuto/protoc-gen-doc.git'
+          url = 'https://github.com/pseudomuto/protoc-gen-doc'
+        }
+      }
+
+      //linux 64 arm
+      artifact("$buildDir/dist/protoc-gen-doc_linux_arm64") {
+        classifier 'linux-aarch_64'
+        extension 'exe'
+      }
+      //linux 64 intel
+      artifact("$buildDir/dist/protoc-gen-doc_linux_amd64") {
+        classifier 'linux-x86_64'
+        extension 'exe'
+      }
+      //mac 64 arm
+      artifact("$buildDir/dist/protoc-gen-doc_darwin_arm64") {
+        classifier 'osx-aarch_64'
+        extension 'exe'
+      }
+      //mac 64 intel
+      artifact("$buildDir/dist/protoc-gen-doc_darwin_amd64") {
+        classifier 'osx-x86_64'
+        extension 'exe'
+      }
+      //windows 64 arm
+      artifact("$buildDir/dist/protoc-gen-doc_windows_arm64") {
+        classifier 'windows-aarch_64'
+        extension 'exe'
+      }
+      //windows 64 intel
+      artifact("$buildDir/dist/protoc-gen-doc_windows_amd64") {
+        classifier 'windows-x86_64'
+        extension 'exe'
+      }
+    }
+  }
+
+  repositories {
+    maven {
+      name = "OSSRH"
+      def releasesRepoUrl = "https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/"
+      def snapshotsRepoUrl = "https://s01.oss.sonatype.org/content/repositories/snapshots/"
+      url = version.endsWith('SNAPSHOT') ? snapshotsRepoUrl : releasesRepoUrl
+      credentials {
+        username = System.getenv("MAVEN_USERNAME")
+        password = System.getenv("MAVEN_PASSWORD")
+      }
+    }
+  }
+}
+
+signing {
+  def signingKey = project.getProperty('signingKey')
+  def signingPassword = project.getProperty('signingPassword')
+  useInMemoryPgpKeys(signingKey, signingPassword)
+  sign publishing.publications.maven
+}
+
+// A strange issue with signing meant that only the first files (with the same name) got signed.
+// To workaround this, rename all executables to include architecture.
+tasks.register('flattenDistDirectory', Copy) {
+  from("$projectDir/dist") {
+    include "**/protoc-gen-doc"
+    include "**/protoc-gen-doc.exe"
+    eachFile { file ->
+      file.name = file.relativePath.parent.lastName
+      file.relativePath = new RelativePath(true, file.relativePath.segments.drop(1))
+    }
+    includeEmptyDirs = false
+  }
+  into "$buildDir/dist"
+}
+
+publish.dependsOn flattenDistDirectory
+signMavenPublication.mustRunAfter flattenDistDirectory

examples/gradle/.gitignore

@@ -0,0 +1,2 @@
+.gradle/
+build/

examples/gradle/README.md

@@ -0,0 +1,5 @@
+# Gradle Example
+
+This is an example project that leverages protoc-gen-doc. You can test it out by running `gradle generateProto`.
+
+After a successful run, you should see `grpc-docs.md` in the _build/generated/source/proto/main/doc_ directory.

examples/gradle/build.gradle

@@ -0,0 +1,29 @@
+plugins {
+  id 'java'
+  id 'com.google.protobuf' version '0.8.18'
+}
+
+protobuf {
+  protoc {
+    artifact = "com.google.protobuf:protoc:3.19.4"
+  }
+  plugins {
+    doc {
+      artifact = "io.github.pseudomuto:protoc-gen-doc:1.5.1"
+    }
+  }
+
+  generateProtoTasks {
+    all().each { task ->
+      task.plugins {
+        doc {
+          option 'markdown,grpc-docs.md'
+        }
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+}

examples/gradle/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'gradle-demo'

examples/gradle/src/main/proto/Demo.proto

@@ -0,0 +1,38 @@
+/**
+ * Demo proto with sample messages.
+ *
+ * This file is really just an example. The data model is completely
+ * fictional.
+ *
+ * For examples of more complex protos, see examples/proto in the protoc-gen-doc repo.
+ */
+syntax = "proto3";
+
+package com.example;
+
+/**
+ * Represents a mail address.
+ */
+message Address {
+  string address_line_1 = 1; /** First address line. */
+  string address_line_2 = 2; /** Second address line. */
+  string address_line_3 = 3; /** Second address line. */
+
+  string town    = 4; /// Address town.
+  string county  = 5; /// Address county, if applicable.
+  string country = 6; /// Address country.
+}
+
+/**
+ * Represents a customer.
+ */
+message Customer {
+  int32 id          = 1; /// Unique customer ID.
+  string first_name = 2; /// Customer first name.
+  string last_name  = 3; /// Customer last name.
+  string details    = 4; /// Customer details.
+
+  string email_address            = 5; /// Customer e-mail address.
+  repeated string phone_number    = 6; /// Customer phone numbers, primary first.
+  repeated Address mail_addresses = 7; /// Customer mail addresses, primary first.
+}

settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'protoc-gen-doc'