I've been wrestling with godoc and found that "go doc" is more for providing usage help from the command line for instance:
go doc -cmd -u
lists the package comment and any functions (or other entities)
go doc *function*
then shows the documentation for an individual function (or other entity)
It seems there is a related tool called godoc.
godoc also seems to generate html on a per package and function basis.
E.g.
godoc -html hello
Generates html containing the package comment only to stdout
godoc is a really confusing name given we have go doc as well!
How can I create static documentation for the whole project?
This is similar to Godoc, create html for entire package which may have been misinterpreted as asking about documentation for packages rather than projects.
I want a build step I can use in a project that may in principle contain many packages and apps.
is there a canonical way to generate documentation for offline use even using godoc?
Go 1.12 (February 2019) is clearer on that:
godoc and go doc
In Go 1.12, godoc no longer has a command-line interface and is only a web server.
Users should use go doc for command-line help output instead.
go doc now supports the -all flag, which will cause it to print all exported APIs and their documentation, as the godoc command line used to do.
cmd/doc: add -all flag to print all documentation for package
Unlike the one for the old godoc, you need the -u flag to see unexported symbols.
This seems like the right behavior: it's consistent.
I was struggling to do this and finally, the thing that worked for me is
make sure you have "wget" installed(I am using mac, so had to install it using x-code)
log in as root user and modify the file called "robots.txt" to remove the line "Disallow : /" as this prevents wget to download the site recursively. The "robots.txt" file should be in $GOROOT path.
open a cmd and start the godocs server using the below command
godoc -http=:6060
I have my local path configured to this port.
Open another cmd and run the below command.
wget -r -np -N -E -p -k http://localhost:6060/pkg/myproject
you can mention the path of the project to have the html docs downloaded for entire project.
You can try Golds, which is an alternate Go docs generation tool (and a local docs server / code reader).
Under your project directory, you can run any of the following commands to generate HTML docs for your Go project:
golds -gen -nouses -plainsrc -wdpkgs-listing=promoted ./...
golds -gen -nouses -wdpkgs-listing=promoted ./...
golds -gen -wdpkgs-listing=promoted ./...
The first command generates the most compact docs and the last one generates the full docs, which size is 6 times of the compact docs.
BTW, I'm the author of Golds. Hope you this tool would satisfy your need.
This can be also achieved using simple wget command for that. Example: snippet
I have a similar issue with that. I'm using GitLab for my projects and I have decide to create and share with some handy GitLab CI YAML templates for Go projects that will automatically generate a static HTML Go documentation without any external packages: https://gitlab.com/tymonx/gitlab-ci
Example: Go Logger documentation
Two nice features:
Embedded Go source code files
Search box is referencing to GitLab
Related
I have a go project where the common functionality is implemented , and there is an another go project for the API which uses common functionality from the first project. API project uses the common project , the imports are done from git hub.
I have added a new functionality to the common project and trying to access that new functionality in API project . I have pushed the code to my branch in git hub (new code not there in master branch of common project) . How can I import the new functionality to API project
you could import packages from specific branch like this
go get <path-to-repo>#<branch>
You're probably looking for go get -u github.com/yourcommonproject. From go help get:
The -u flag instructs get to update modules providing dependencies
of packages named on the command line to use newer minor or patch
releases when available.
The -x flag might also be useful in debugging:
The -x flag prints commands as they are executed. This is useful for
debugging version control commands when a module is downloaded directly
from a repository.
Useful relevant links:
https://golang.cafe/blog/how-to-upgrade-golang-dependencies.html
https://go.dev/doc/modules/managing-dependencies
I want to see locally how my package documentation will look. That is, I want to see the same kind of thing you see on godoc.org, but locally.
I have a simple example folder locally, but I can't get it to work. It correctly outputs text documentation:
~/code/go/gonotes (master) $ godoc .
PACKAGE DOCUMENTATION
package gonotes
import "."
FUNCTIONS
func Blah()
Here is header
Blah is function being use to test:
- go documentation
- blah like things
It is nice
But if I run godoc -http=:6060, and navigate to http://localhost:6060/, I see essentially the same content I'd see on the golang.com homepage. http://localhost:6060/gonotes displays
lstat $GOROOT/gonotes: no such file or directory
Am I misunderstanding how the -http works? Is there any way to preview the http version of my docs locally?
UPDATE
I was able to get it to appear by copying the files into src/gonotes and then running:
GOPATH=/Users/jonah/code/go/gonotes godoc -http=:6060
so that the actual files were available at /Users/jonah/code/go/gonotes/src/gonotes.
This has the side effect of not showing any of the Third part libs installed in my default GOPATH, so I'd still like to find a solution that just allows me to add the current directory, as is, without adding src/curdir to it, and still have it show up.
In GOPATH mode
godoc -http will serve doc of all available packages, including the standard library. Worry not, your own packages are amongst them, just look again. As a shortcut, just type http://localhost:6060/pkg/your/package.
In module-aware mode
GOPATH and modules are mutually exclusive, see Go Modules does not recognize files under GOPATH. The godoc tool is not module-aware, and it is being deprecated (see deprecation warning), so for now if you want to see your package docs of modules locally in godoc, you have to resort to putting their sources in an src folder.
"Workaround" for seeing docs of module's:
Put the repo in a folder like /some/folder/src
Start godocs with godoc -goroot=/some/folder -http=:6060
See related issue: support Go modules
Also groups discussion: Is the go 1.11 godoc tool 'module-aware'?
godoc -html generates documents for only one package. However, I want to ship the project with all documents for all packages, just like when I run godoc -http. With that, I could find all packages and navigate through them from the browser.
Is it possible to generate HTML pages for all packages linked together through godoc -html?
You have two questions here:
Is it possible to generate HTML pages for all packages linked together through godoc -html?
No. Because it is not implemented into godoc (https://godoc.org/golang.org/x/tools/cmd/godoc).
The other question:
How can I generate HTML documents for all packages inside a folder
using godoc
I think the simplest way is to start godoc with the http flag: godoc -http=:6060
Then you navigate to the folder you want to get the docs. For that url you can use a webcrawler for getting the html documentation. There are already some crawler in Go (https://godoc.org/?q=crawler), if you don't want to write a crawler by your own.
I developed Golds, which is an alternate Go docs generation tool (and a local docs server / code reader). Hope you this tool would satisfy your need.
Under your project directory, you can run any of the following commands to generate HTML docs for your Go project:
golds -gen -nouses -plainsrc -wdpkgs-listing=promoted ./...
golds -gen -nouses -wdpkgs-listing=promoted ./...
golds -gen -wdpkgs-listing=promoted ./...
The first command generates the most compact docs and the last one generates the full docs, which size is 6 times of the compact docs.
I have a Go sub-project in a multi-language project repo. I want to be able to use 'go get' and 'go doc'.
My layout looks like:
proton-c/bindings/go/<my packages>
examples/go/<some go examples>
I set up go-import tags on the website and created a "go" symlink in the repo root so I can go get qpid.apache.org/proton/go/<package>. It works!! It clones the entire project repo into my GOPATH but that's ok.
The problem is if I run godoc -http it does the following bad things:
ignores the root "go" symlink entirely
documents my packages as "qpid.apache.org/proton/proton-c/bindings/go/"
shows the package path to the directory with nothing in it.
The command line "godoc qpid.apache.org/proton/go/package" DOES do the right thing so godoc can extract the doc correctly but the "directory browsing" feature of godoc -http is picking up too much and not following the symlink.
So can I restrict/control what godoc picks as documentation?
I read https://github.com/golang/gddo/wiki/Source-Code-Links, but I don't think it helps my problem, could be wrong.
I am reading on the article how to generate an Apple-like HTML documentation at here. My questions are what the command lines are used for. How can we combine command lines and appledoc xcode project to generate a HTML.
I'm the author of appledoc tool. The tool is intended to be used as answered by Caleb above. Recommended installation method is to clone repository from GitHub, open project in Xcode, build and optionally copy binary to your path as suggested above. Additionally, you must also copy template files required for running the tool to one of predefined paths. All the steps required are described in the readme file on appledoc page on GitHub, see Quick Install section.
There are also other methods for installing - all contribution from users:
You can use install-appledoc.sh script included in the git repository.
There's also homebrew recipe available, although it doesn't install template files to my understanding (see this link).
For any additional questions go to appledoc Google group. I just created it few days ago, so there's no content at the moment of this writing, but feel free to ask questions there.
I haven't used 'appledoc', but from a quick look at the page you linked it appears that it's an open-source command-line utility. So the first step will be to compile the 'appledoc' program itself, and then stick it in a directory that's in your path, such as /usr/local/bin or ~/bin/.
The next step is to try to use it to generate some documentation (assuming that you've already created the markdown files that it consumes). Open a terminal window, navigate to the directory where your files are, and then use the command given at the top of the page that you linked:
appledoc --project-name appledoc --project-company "Gentle Bytes" --company-id com.gentlebytes --output ~/help .
If you want to use 'appledoc' to regenerate your documentation every time you build some project, you can add a "Run Script" build phase to an existing target in your project, or create a new target just for documentation that has nothing but a "Run Script" build phase. Either way, the script in that phase should be shell script containing a command similar to the one above (though you'll probably want to specify the source directory explicitly rather than just using the 'current' directory, i.e. .).
As I found on this post, you can generate a complete HTML documentation of your code with this command line:
appledoc --project-name BabelCPP --project-company "My Name"
--company-id com.mycompany --no-create-docset --output ./doc/ .
The last "." is the path to your code.