posener/goreadme

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

goreadme's Issues

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

Add google analytics

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 :)

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.

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!

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?

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.

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!

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.

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.

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/.)

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

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{ ... }

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...

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