docweaver

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.

---

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

Gin Example

main.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

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

Documentation

Index

• Constants
• func GetAssetsDir() string
• func GetAssetsRoutePrefix() string
• func GetRoutePrefix() string
• func GetSourcesFilePath() string
• type Cleaner
• type DocHandler
• type Page
• type Product
  • func (p *Product) Key() string
  • func (p *Product) Url() string
• type ProductRepository
  • func GetRepository(dir string) ProductRepository
• type Publisher
• type Updater
• type UpdaterPublisher
  • func GetPublisher() UpdaterPublisher
  • func GetPublisherWithDocsDir(docsDir string) UpdaterPublisher

Constants

const (
	EnvKeyDocsDir           string = "DW_DOCS_DIR"            // Docs directory environment key.
	EnvKeyAssetsDir         string = "DW_ASSETS_DIR"          // Assets directory environment key.
	EnvKeyRoutePrefix       string = "DW_ROUTE_PREFIX"        // Route prefix environment key.
	EnvKeyAssetsRoutePrefix string = "DW_ASSETS_ROUTE_PREFIX" // Assets route prefix environment key.
	EnvKeySourcesFile       string = "DW_SOURCES_FILE"        // Sources file environment key.
	EnvKeyShowLogs          string = "DW_SHOW_LOGS"           // Show logs environment key.

)

Functions

func GetAssetsDir

func GetAssetsDir() string

GetAssetsDir returns configured assets directory. env key: DW_ASSETS_DIR

func GetAssetsRoutePrefix

func GetAssetsRoutePrefix() string

GetAssetsRoutePrefix returns configured assets route prefix. env key: DW_ASSETS_ROUTE_PREFIX

func GetRoutePrefix

func GetRoutePrefix() string

GetRoutePrefix returns configured documentation route prefix. env key: DW_ROUTE_PREFIX

func GetSourcesFilePath

func GetSourcesFilePath() string

GetSourcesFilePath returns configured sources file path. env key: DW_SOURCES_FILE

Types

type Cleaner

type Cleaner interface {
	CleanTempVersions() error
}

type DocHandler

type DocHandler interface {
	GetDocsDir() string
}

type Page

type Page struct {
	UrlPath string
	Title   string
	Content string
	Version string
	Product *Product
	Index   *Page
}

type Product

type Product struct {
	Name          string
	Description   string
	BaseUrl       string
	ImageUrl      string
	Versions      []string
	LatestVersion string
	Index         *Page
	// contains filtered or unexported fields
}

func (*Product) Key

func (p *Product) Key() string

func (*Product) Url

func (p *Product) Url() string

type ProductRepository

type ProductRepository interface {
	Cleaner
	FindAllProducts() ([]Product, error)
	FindProduct(productName string) (*Product, error)
	GetDir() string
	GetPage(productName, version, pagePath string) (*Page, error)
	GetIndex(productName string) (*Page, error)
	ListProductKeys() ([]string, error)
}

func GetRepository

func GetRepository(dir string) ProductRepository

type Publisher

type Publisher interface {
	Cleaner
	DocHandler
	Publish(productKey string, source string, shouldUpdate bool)
	// PublishFromSources publishes all documentation configured in sources file. i.e. env: DW_SOURCES_FILE
	PublishFromSources() (int, error)
}

type Updater

type Updater interface {
	DocHandler
	Update(productKeys ...string)
	UpdateAll()
}

type UpdaterPublisher

type UpdaterPublisher interface {
	Updater
	Publisher
}

UpdaterPublisher is a hybrid publisher/publisher.

func GetPublisher

func GetPublisher() UpdaterPublisher

GetPublisher returns the default instance of UpdaterPublisher.

func GetPublisherWithDocsDir

func GetPublisherWithDocsDir(docsDir string) UpdaterPublisher

GetPublisherWithDocsDir returns an instance of UpdaterPublisher with the provided [dir].