posener/goreadme

Generate readme file from Go doc. Now available as a Github action!

goreadme

Package goreadme generates readme markdown file from go doc.

The package can be used as a command line tool and as Github action, described below:

Github Action

Github actions can be configured to update the README file automatically every time it is needed. Below there is an example that on every time a new change is pushed to the main branch, the action is trigerred, generates a new README file, and if there is a change - commits and pushes it to the main branch. In pull requests that affect the README content, if the GITHUB_TOKEN is given, the action will post a comment on the pull request with changes that will be made to the README file.

To use this with Github actions, add the following content to .github/workflows/goreadme.yml. See ./action.yml for all available input options.

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
permissions:
  # Goreadme needs permissions to update pull requests comments and change contents.
  pull-requests: write
  contents: write
jobs:
    goreadme:
        runs-on: ubuntu-latest
        steps:
        - name: Check out repository
          uses: actions/checkout@v2
        - name: Update readme according to Go doc
          uses: posener/goreadme@v1
          with:
            badge-travisci: 'true'
            badge-codecov: 'true'
            badge-godoc: 'true'
            badge-goreadme: 'true'
            # Optional: Token allows goreadme to comment the PR with diff preview.
            GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'

Use as a command line tool

$ GO111MODULE=on go get github.com/posener/goreadme/cmd/goreadme
$ goreadme -h

Why Should You Use It

Both Go doc and readme files are important. Go doc to be used by your user's library, and README file to welcome users to use your library. They share common content, which is usually duplicated from the doc to the readme or vice versa once the library is ready. The problem is that keeping documentation updated is important, and hard enough - keeping both updated is twice as hard.

Go Doc Instructions

The formatting of the README.md is done by the go doc parser. This makes the result README.md a bit more limited. Currently, goreadme supports the formatting as explained in godoc page, or here. Meaning:

• A header is a single line that is separated from a paragraph above.

• Code block is recognized by indentation as Go code.

func main() {
  ...
}

• Inline code is marked with backticks.

• URLs will just automatically be converted to links: https://github.com/posener/goreadme

Additionally, the syntax was extended to include some more markdown features while keeping the Go doc readable:

• Bulleted and numbered lists are possible when each bullet item is followed by an empty line.

• Diff blocks are automatically detected when each line in a code block starts with a ' ', '-' or '+':

-removed line starts with '-'
 remained line starts with ' '
+added line starts with '+'

• A repository file can be linked when providing a path that start with [./](./): ./goreadme.go.

• A link can have a link text by prefixing it with parenthesised text: goreadme page.

• A link to repository file and can have a link text: goreadme main file.

• An image can be added by prefixing a link to an image with (image/<image title>):

Testing

The goreadme tests the test cases in the ./testdata directory. It generates readme files for all the packages in that directory and asserts that the result readme matches the existing one. When modifying goreadme behavior, there is no need to manually change these readme files. It is possible to run WRITE_READMES=1 go test ./... which regenerates them and check the changes match the expected (optionally using git diff).

Sub Packages

• cmd/goreadme: Goreadme command line tool and Github action

---

Readme created from Go doc with goreadme

goreadme's Issues

401: Bad credentials

Good day. Trying goreadme get all kind of errors:

> goreadme github.com/posener/goreadme
2021/04/28 11:59:26 Getting github.com/posener/goreadme
Failed: failed getting github.com/posener/goreadme: 401: Bad credentials (https://api.github.com/repos/posener/goreadme)

PS ..\pg_timetable > goreadme -recursive internal\pgengine
2021/04/28 12:00:40 Getting internal\pgengine
Failed: failed getting internal\pgengine: Import path not valid:
PS ..\pg_timetable > goreadme -recursive internal/pgengine
2021/04/28 12:00:44 Getting internal/pgengine
Failed: failed getting internal/pgengine: Import path not valid:

PS ..\pg_timetable > goreadme -recursive .
2021/04/28 12:01:42 Getting .
Failed: failed getting .: Import path not valid:

Neither manual nor error messages contain useful information for me. I would like to ask you if I'm doing something incredibly wrong before investigating source code.

Thanks in advance!

Store stars and order by stars

goreadme doesnt read doc string

i used goreadme in some projects and i really love it. today i started a new project and tried to use goreadme.... it just produces the default output

$ goreadme
2021/09/24 18:30:19 Getting .
#

---
Readme created from Go doc with [goreadme](https://github.com/posener/goreadme)

the docs are writting in this file: https://git.xsfx.dev/xsteadfastx/workgroups/src/branch/main/workgroups.go

its about this repo: https://git.xsfx.dev/xsteadfastx/workgroups

maybe someone has an idea. i use goreadme version 1.4.1

Links can include backticks which looks bad in inline code

See in https://github.com/posener/gitfs/pull/19/files

The change is:

+ Use binary-packing with `go generate`: To generate all filesystems used
+ by a project add `//go:generate gitfs [./...`](./...`) in the root of the project.
+ To generate only a specific filesystem add `//go:generate gitfs $GOFILE` in
+ the file it is being used.

internal/markdown/comment.go: consider exposing whole package or ToMarkdown

Would be useful to be able to import and use ToMarkdown as defined in here https://github.com/posener/goreadme/blob/master/internal/markdown/comment.go#L284.

Might be helpful to just the internal package altogether. Not sure...

Add google analytics

Do not make assumptions about environment (CI - Github Actions)

I can understand you were trying to make things more automatic but please replace the the check for at:

https://github.com/posener/goreadme/blob/master/cmd/goreadme/main.go#L120

To require this to be a flag instead of assuming CI is an environment variable being set by Github actions. This tripped me up because I didn't want to use your action because it tries to commit the changes. I opt'd out of using the action to run the tool directly, but my workflow was failing due to this CI assumption. I managed to get around this by overriding the env of CI to false but I would hate for others to run into this and get stuck.

I would suggest updating your github action to have an input for CI mode and the ability to skip commiting the updated README.

Hardcoded Branch Name

Seems for some of the badges, the Branch name is hardcoded into the template. Would be good to make that dynamic as Github has changed the defaults from master to main on new repositories

I see a attempt to fix this was made in #102 (along with other fixes). Could that be cherry picked out?

Option to include exported types

To get closer to the output of go doc, include the types of the package
i.e.
type Config struct{ ... }

Non-compliant naming of environment variables

Environment variables, as per specification, should be UPPERCASE and use '_' as separator. Current code using lowercase and '-'.

https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html

I don't think most *UNIX shells will even let you set environment variables that are lowercase and use a '-'

https://github.com/posener/goreadme/blob/master/cmd/goreadme/main.go#L30
https://github.com/posener/goreadme/blob/master/cmd/goreadme/main.go#L35
https://github.com/posener/goreadme/blob/master/cmd/goreadme/main.go#L37

Also might be help to add some information to the help that details what environment need to be set specifically the GITHUB_TOKEN.

Useful took. I'm excited to start using the tool once I can specify a git token for a private repo :)

Obsolete dependency on posener/goaction v1.0.3

Hi there, that's what I see when I try to replicate installation command from Readme in an existing project:

$ go version
go version go1.14.2 darwin/amd64
$ GO111MODULE=on go get github.com/posener/goreadme/cmd/goreadme
go: downloading github.com/posener/goreadme v1.3.2
go: found github.com/posener/goreadme/cmd/goreadme in github.com/posener/goreadme v1.3.2
go get: github.com/posener/[email protected] requires
	github.com/posener/[email protected]: reading github.com/posener/goaction/go.mod at revision v1.0.3: unknown revision v1.0.3

Badge Path of `.`

Hi there, thanks for a nice tool. I'm running it with:

goreadme --skip-examples --badge-godoc --badge-goreportcard

directly from the project, and I notice that even though the project name is detected correctly and displayed as the top-level markdown heading, it's not respected in the badge URLs:

[![GoDoc](https://img.shields.io/badge/pkg.go.dev-doc-blue)](http://pkg.go.dev/.)
[![Go Report Card](https://goreportcard.com/badge/.)](https://goreportcard.com/report/.)

Support for badges

Hi there, I can see some code and templates and such around handling badges (Travis CI, GoDoc, GolangCI, etc) but it doesn't seem to be fully wired up.
I'd like to use goreadme for some of my own packages/repos, but would really miss my badges if they weren't handled by a tool like this and ended up going away.
Is this something that will be covered in the near future? I'm more than happy to help out with a PR on this.

Result contains '(MISSING)' text

In the https://github.com/preaction/mojo.go repository, the README is generated from doc.go. However, the generated README.md contains some things that are not in the original:

 	app := mojo.NewApplication()
-	app.Renderer.AddTemplate("greet", "Hello, <% .Stash.name %>!\n")
+	app.Renderer.AddTemplate("greet", "Hello, <%!.(MISSING)Stash.name %!>(MISSING)!\n")
 	app.Routes.Get( "/:name", mojo.Stash{"name": "World"}).To( GreetHandler )
 	app.Start()

How can I remove those changes? I'll be happy to develop a PR if needed.

Flag for output destination

The only way to make a file using this tool as CLI is to redirect the stdout to a file. It would be helpful to have a flag for where to output the markdown content.

Generated file notice in raw MD file

It would be nice if the tool could add a comment to the .md output as an html comment so that it is clear that the file is generated and should not be directly edited. This is most useful in team projects were others may not be aware of this tool and make edits to the file directly.

Diff recognition interferes with command usage documentation

First, thanks for creating goreadme. It's a nice solution to a bothersome problem!

In a project with several cmds, I'm trying to automatically get the cmd's usage help into the readme. So I wrote some build code to call each installed cmd with "-h" and put the output into doc.go, e.g.

/*
Usage of rir:
  -c uint
    	Length of each chunk to be RIR expanded. 0 means all of input in one chunk.
  -n int
    	number of countin beats before each segment (default 4)
  -o uint
    	number of bars to overlap chunks. Must be less than chunkLength

*/
package main

But goreadme notices the leading '-' chars and renders the above as:

Usage of rir:

```diff
-c uint
  	Length of each chunk to be RIR expanded. 0 means all of input in one chunk.
-n int
  	number of countin beats before each segment (default 4)
-o uint
  	number of bars to overlap chunks. Must be less than chunkLength
```

Is there a way to suppress the diff recognition?

Thanks!

Does it need to support line feeds

When my note has many lines, it doesn't recognize the line break markers in the document.
Maybe it's //, maybe it's \n, and eventually it merges all of them into one line