https://github.com/bloodorangeio/speck
Tool to extract and combine hidden text across multiple files (for documentation purposes)
https://github.com/bloodorangeio/speck
docs documentation go golang spec specification
Last synced: 5 months ago
JSON representation
Tool to extract and combine hidden text across multiple files (for documentation purposes)
- Host: GitHub
- URL: https://github.com/bloodorangeio/speck
- Owner: bloodorangeio
- License: apache-2.0
- Created: 2020-05-28T17:21:01.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2020-05-29T22:07:39.000Z (about 6 years ago)
- Last Synced: 2024-06-20T13:28:27.724Z (about 2 years ago)
- Topics: docs, documentation, go, golang, spec, specification
- Language: Go
- Homepage:
- Size: 14.6 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Speck
[](https://github.com/bloodorangeio/speck/actions?query=workflow%3Abuild) [](https://godoc.org/github.com/bloodorangeio/speck)
Speck is a tool that allows you to extract text between `` tags found within one or more files.
It is agnostic to the format or extension of files used as input.
The result of the combined extracted text is printed to stdout.
This might be useful, for example, for building documentation from special comments placed in your source code.
## Installing
Requires Go 1.14+.
```
go build ./speck.go
sudo mv ./speck /usr/local/bin
```
## How to use
Start with a file containing `` tags within, such as the following `main.go`:
```go
package main
/*
# Hello World
*/
import (
"fmt"
)
func main() {
/*
This is a test.
*/
fmt.Println("hello world")
}
```
Then run `speck`, and direct the output to a file such as `example.md`:
```
speck main.go > example.md
```
The contents of `example.md`:
```
# Hello World
This is a test.
```
Notice the optional `tab` attribute,
which will instruct Speck to trim x number of tabs from the left side of each line within a section.
Speck can also be used with multiple files, combining the output in order.
You can also leverage shell globbing. Here is an example using some test files within this repo:
```
speck testdata/go-test-suite-example/*.go
```
which would be the same as running
```
speck testdata/go-test-suite-example/00_setup_test.go \
testdata/go-test-suite-example/02_second_test.go \
testdata/go-test-suite-example/01_first_test.go
```
## Note on inner HTML
Sometimes you might want to document things like look like HTML tags.
Here's an example using `` to represent a URL part:
```
This is my API request: `POST /api/stuff/`
```
This is supported, with the caveat that is must not be on the same
line as the string "speck". As in, you can do this:
```
This is my API request: `POST /api/stuff/`
```
but you cannot do this:
```
This is my API request: `POST /api/stuff/`
```
Otherwise you will end up with `` going missing in the output. This is needed due to HTML parsing madness.
The issue is demonstrated in the `TestDisappearingTag` test found in [speck_test.go](./speck_test.go).
If you can fix this, PRs are accepted by all means.