https://github.com/joeshaw/doc-extract
Go tool for extracting text from specially tagged Go comments
https://github.com/joeshaw/doc-extract
api-blueprint comments extract go golang sphinx
Last synced: 3 months ago
JSON representation
Go tool for extracting text from specially tagged Go comments
- Host: GitHub
- URL: https://github.com/joeshaw/doc-extract
- Owner: joeshaw
- License: mit
- Created: 2017-10-25T18:39:25.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-04-07T14:04:58.000Z (about 5 years ago)
- Last Synced: 2025-08-18T13:44:14.732Z (10 months ago)
- Topics: api-blueprint, comments, extract, go, golang, sphinx
- Language: HTML
- Size: 13.7 KB
- Stars: 7
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# doc-extract
doc-extract is a tool for extracting specially tagged comments in Go
source code. Tagged comments start with a blank line containing
`+extract`. Both grouped line comments (`//`) and block comments (`/*
*/`) are supported.
## Installation
Go 1.16 and later:
go install github.com/joeshaw/doc-extract@latest
Go 1.15 and earlier:
go get -u github.com/joeshaw/doc-extract
## Usage
Simply tag comments in your Go source code with `+extract` as the first
line of your comment. For example,
```go
package main
// +extract
// API Documentation
// =================
//
// (TODO: add documentation)
```
Then run the `doc-extract` command, providing it with a directory of
Go source files and an output file:
doc-extract ./example example.txt
Source files are processed in lexicographic order, _except_ that a file
named `doc.go` gets highest priority. Comments within a file are
processed in the order they appear.
This predictable ordering allows you to add, for instance, a header to
the output file by adding it to `doc.go`.
## Example
The `example` directory contains an [example using API
Blueprint](example/README.md).
## Motivation
This tool is especially useful for extracting documentation from
comments when GoDoc isn't appropriate. For example, documentation for
HTTP APIs. This could be used to extract [API
Blueprint](https://apiblueprint.org/) for processing by
[Snowboard](https://github.com/bukalapak/snowboard). Or it could be
used to pull ReStructured Text (RST) for processing by
[Sphinx](http://sphinx-doc.org/) and the
[httpdomain](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/)
extension.
This replaces my now-deprecated
[rst-extract](https://github.com/joeshaw/rst-extract) tool.
## Contributing
Issues and pull requests are welcome. When filing a PR, please make
sure the code has been run through `gofmt` and that the tests pass.
## License
MIT