stuff for generating docs

.github/workflows/autodoc.yml

@@ -0,0 +1,20 @@
+name: Auto-Doc
+on: 
+  pull_request:
+    branches:
+      - main
+    types:
+      - closed
+
+jobs:
+  autodoc:
+    runs-on: ubuntu-latest
+    name: "Run commands to generate documentation"
+    if: github.event.pull_request.merged == true
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Process markdown files
+        run: |
+          find . -name '*.md' | xargs perl tools/autodoc.pl
+ 

.github/workflows/ci.yml

@@ -11,6 +11,9 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
+      - name: Check documentation generator
+        run: |
+          find . -name '*.md' | xargs env AUTODOC_DRYRUN=1 perl tools/autodoc.pl
       - name: Install Go stable version
         uses: actions/setup-go@v2
         with:

README.md

@@ -4,6 +4,11 @@
 can be fetched via HTTP, but keep the cached content up-to-date based on periodic
 refreshing.
 
+# SYNOPSIS
+
+<!-- INCLUDE(httprc_example_test.go) -->
+<!-- END INCLUDE -->
+
 # Sequence Diagram
 
 ```mermaid

httprc_example_test.go

@@ -0,0 +1,76 @@
+package httprc_test
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"time"
+
+	"github.com/lestrrat-go/httprc"
+)
+
+func Example() {
+	var mu sync.RWMutex
+
+	msg := `Hello World!`
+
+	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set(`Cache-Control`, fmt.Sprintf(`max-age=%d`, 3))
+		w.WriteHeader(http.StatusOK)
+		mu.RLock()
+		fmt.Fprintf(w, msg)
+		mu.RUnlock()
+	}))
+	defer srv.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	errSink := httprc.ErrSinkFunc(func(err error) {
+		log.Printf("%s", err)
+	})
+
+	c := httprc.New(ctx,
+		httprc.WithErrSink(errSink),
+		httprc.WithRefreshWindow(time.Second), // force checks every second
+	)
+
+	c.Register(srv.URL, httprc.WithHTTPClient(srv.Client()))
+
+	payload, err := c.Get(ctx, srv.URL)
+	if err != nil {
+		log.Printf("%s", err)
+		return
+	}
+
+	//nolint:forcetypeassert
+	if string(payload.([]byte)) != `Hello World!` {
+		log.Printf("payload mismatch: %s", payload)
+		return
+	}
+
+	mu.Lock()
+	msg = `Goodbye World!`
+	mu.Unlock()
+
+	time.Sleep(4 * time.Second)
+
+	payload, err = c.Get(ctx, srv.URL)
+	if err != nil {
+		log.Printf("%s", err)
+		return
+	}
+
+	//nolint:forcetypeassert
+	if string(payload.([]byte)) != `Hello World!` {
+		log.Printf("payload mismatch: %s", payload)
+		return
+	}
+
+	cancel()
+
+	// OUTPUT:
+}

httprc_test.go

@@ -29,7 +29,7 @@ func TestCache(t *testing.T) {
 	defer cancel()
 
 	var called int
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		select {
 		case <-ctx.Done():
 			return

queue.go

@@ -21,6 +21,12 @@ type ErrSink interface {
 	Error(error)
 }
 
+type ErrSinkFunc func(err error)
+
+func (f ErrSinkFunc) Error(err error) {
+	f(err)
+}
+
 // Transformer is responsible for converting an HTTP response
 // into an appropriate form of your choosing.
 type Transformer interface {

tools/autodoc.pl

@@ -0,0 +1,69 @@
+#!perl
+use strict;
+use File::Temp;
+
+# Accept a list of filenames, and process them
+# if any of them has a diff, commit it
+
+my @files = @ARGV;
+my @has_diff;
+for my $filename (@files) {
+    open(my $src, '<', $filename) or die $!;
+
+    my $output = File::Temp->new(SUFFIX => '.md');
+    my $skip_until_end;
+    for my $line (<$src>) {
+        if ($line =~ /^<!-- END INCLUDE -->$/) {
+            $skip_until_end = 0;
+        } elsif ($skip_until_end) {
+            next;
+        }
+        if ($line !~ /(^<!-- INCLUDE\(([^\),]+)(?:,([^\)]+))?\) -->)$/) {
+            $output->print($line);
+            next;
+        }
+        $output->print("$1\n");
+
+        my $include_filename = $2;
+        my $options = $3;
+
+        $output->print("```go\n");
+        my $content = do {
+            open(my $file, '<', $include_filename) or die "failed to include file $include_filename from source file $filename: $!";
+            local $/;
+            <$file>;
+        };
+        $content =~ s{^(\t+)}{"  " x length($1)}gsme;
+        $output->print($content);
+        $output->print("```\n");
+        $output->print("source: [$include_filename](https://github.com/lestrrat-go/jwx/blob/$ENV{GITHUB_REF}/$include_filename)\n");
+
+        # now we need to skip copying until the end of INCLUDE
+        $skip_until_end = 1;
+    }
+    $output->close();
+    close($src);
+
+    if (!$ENV{AUTODOC_DRYRUN}) {
+        rename $output->filename, $filename or die $!;
+        my $diff = `git diff $filename`;
+        if ($diff) {
+            push @has_diff, $filename;
+        }
+    }
+}
+
+if (!$ENV{AUTODOC_DRYRUN}) {
+    if (@has_diff) {
+        # Write multi-line commit message in a file
+        my $commit_message_file = File::Temp->new(SUFFIX => '.txt');
+        print $commit_message_file "autodoc updates\n\n";
+        print "  - $_\n" for @has_diff;
+        $commit_message_file->close();
+        system("git", "remote", "set-url", "origin", "https://github-actions:$ENV{GITHUB_TOKEN}\@github.com/$ENV{GITHUB_REPOSITORY}") == 0 or die $!;
+        system("git", "config", "--global", "user.name", "$ENV{GITHUB_ACTOR}") == 0 or die $!;
+        system("git", "config", "--global", "user.email", "$ENV{GITHUB_ACTOR}\@users.noreply.github.com") == 0 or die $!;
+        system("git", "commit", "-F", $commit_message_file->filename, @files) == 0 or die $!;
+        system("git", "push", "origin", "HEAD:$ENV{GITHUB_REF}") == 0 or die $!;
+    }
+}