docweaver

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.

Installation & Usage

Installation

go get github.com/reliqarts/go-docweaver

Setup

Example .env:

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

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

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")
}

// ...

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,
		})
	}
}

// ...

🍻 cheers