Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reliqarts/go-docweaver
Product documentation generation package for Go.
https://github.com/reliqarts/go-docweaver
documentation docweaver gin golang golang-package markdown
Last synced: about 1 month ago
JSON representation
Product documentation generation package for Go.
- Host: GitHub
- URL: https://github.com/reliqarts/go-docweaver
- Owner: reliqarts
- License: mit
- Created: 2021-11-13T05:38:17.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-17T17:05:15.000Z (11 months ago)
- Last Synced: 2024-06-20T01:57:18.507Z (6 months ago)
- Topics: documentation, docweaver, gin, golang, golang-package, markdown
- Language: Go
- Homepage: https://reliqarts.com/docs/docweaver
- Size: 38.1 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Docweaver (Go)
An easy-to-use product documentation package in Golang.
Docweaver is suitable for product documentation and/or knowledge bases. Converts folder(s) of .md files into full-bread
complete documentation. This package is without UI elements and templates, all freedom regarding final presentation is
given to the end-user.
PHP/Laravel version is available [here](https://github.com/reliqarts/laravel-docweaver).
[](https://pkg.go.dev/github.com/reliqarts/go-docweaver)
[](https://github.com/reliqarts/go-docweaver/actions?query=workflow:CI)
[](https://codecov.io/gh/reliqarts/go-docweaver)
[](https://goreportcard.com/report/github.com/reliqarts/go-docweaver)
[](https://codeclimate.com/github/reliqarts/go-docweaver/maintainability)
---
## Installation & Usage
### Installation
```bash
go get github.com/reliqarts/go-docweaver
```
### Setup
Example .env:
```dotenv
DW_DOCS_DIR=./tmp/docs # Where documentation repos (archives) should be stored.
DW_ASSETS_DIR=./tmp/doc-assets # Where documentation assets should be accessed from.
DW_ROUTE_PREFIX=docs # Documentation route prefix.
DW_ASSETS_ROUTE_PREFIX=doc-assets # Route prefix for assets.
DW_SOURCES_FILE=./doc-sources.yml # Sources file location.
DW_SHOW_LOGS=true # Whether logs should be printed.
```
Example files:
- [doc-sources.yml](https://github.com/reliqarts/go-docweaver/blob/main/testdata/doc-sources.yml)
#### Documentation Directory
The documentation directory is the place where you put your project documentation directories. It may be changed with
the environment variable `DW_DOCS_DIR`. The default documentation directory is `./tmp/docs`.
#### Structure
Each project directory should contain separate folders for each documented version. Each version must have at least
two (2) markdown files, namely `documentation.md` and `installation.md`, which serve as the index (usually shown in sidebar) and initial
documentation pages respectively.
```
[doc dir]
│
└─── Project One
│ └── 1.0
│ └── 2.1
│ └── .docweaver.yml # meta file (optional)
│ └── documentation.md # sidebar nav
│ └── installation.md # initial page
│
└─── Project Two
```
#### Meta File
Configurations for each doc version may be placed in `.docweaver.yml`. The supported settings are:
- #### name
Product name.
- #### description
Product description.
- #### image_url
Product image url. This may be an absolute url (e.g. `http://mywebsite.com/myimage.jpg`) or an image found in
the `images` resource directory.
To use the `foo.jpg` in the `images` directory you would set `image_url` to `{{docs}}/images/foo.jpg`.
### Usage
Gin Example
###### main.go
```go
package main
import (
"github.com/gin-gonic/gin"
"github.com/reliqarts/go-docweaver"
)
func main() {
router := gin.New()
router.GET(docweaver.GetRoutePrefix(), handlers.Documentation())
router.GET(fmt.Sprintf("%s/*path", docweaver.GetRoutePrefix()), handlers.Documentation())
router.Static(docweaver.GetAssetsRoutePrefix(), docweaver.GetAssetsDir())
_ = (router).Run("localhost:8080")
}
// ...
```
###### handlers.go
```go
package handlers
import (
"github.com/gin-gonic/gin"
"github.com/reliqarts/go-docweaver"
"net/http"
)
// ...
func Documentation() gin.HandlerFunc {
return func(c *gin.Context) {
path := c.Param("path")
dw := docweaver.GetRepository("")
if path == "/" || path == "" {
products, err := dw.FindAllProducts()
if err != nil {
c.HTML(code, "error.gohtml", gin.H{
"errorCode": http.StatusInternalServerError,
"errorMessage": err,
})
return
}
c.HTML(http.StatusOK, "docs/index.gohtml", gin.H{
"products": products,
})
return
}
productKey, version, pagePath := "", "", ""
pageParts := strings.Split(path, "/")
if len(pageParts) >= 2 {
productKey = pageParts[1]
}
if len(pageParts) >= 3 {
version = pageParts[2]
}
if len(pageParts) >= 4 {
pagePath = pageParts[3]
}
page, err := dw.GetPage(productKey, version, pagePath)
if err != nil {
errMsg := fmt.Sprintf("Page not found. %s", err)
c.HTML(http.StatusNotFound, "error.gohtml", gin.H{
"errorCode": http.StatusNotFound,
"errorMessage": errMsg,
})
c.Abort()
return
}
c.HTML(http.StatusOK, "documentation/show.gohtml", gin.H{
"page": page,
})
}
}
// ...
```
---
:beers: cheers