swdocs

Index all of your software docs easily!

SwDocs offers a single place with all the relevant links to your software, stop wasting your time trying to find relevant docs across multiple systems:

• Google Drive
• Wikis
• Readthedocs
• Godocs
• Cargo docs
• Github
• Grafana
• Kibana
• Upstream websites
• Prometheus Dashboards
• (...)

Have a one stop shop! By being an indexer with templated views across all pages, SwDocs has some advantages:

• Harder for people to get creative w/ the docs or diverge;
• Very simple to get up and running, it is a single binary;
• Run for yourself in your machine or in a server for your organization;
• Offers a web ui (without javascript) and a CLI to navigate your docs;
• Have all the relevant links to your code base with your code base;
• Edit the links from where you edit your code, let your CI system update your docs when you push new code.

You can use SwDocs locally or deploy on a server, for the latter anyone in your organization will have a simple and predictable URL to find any docs for a particular software.

For a software called foo, you can embed an URL like "http://swdocs.com/foo" in your foo software's --help!

Install

Download a release from the Releases page and unpack the binary where you want

> tar -xvf swdocs-1.0.0.tar.gz -C /tmp
> cd /tmp
> ./swdocs --help

You can also clone this repo and build yourself, run make build.

Usage

You can use SwDocs from a browser or from the CLI. You start by running the server and creating some docs through its apply CLI and then you can visualize and search from your favorite browser or through CLI operations like get and list.

The web app

Running

# Start the swdocs server w/ defaults and go to http://localhost:8087
> swdocs serve

# Create a .dev.env file as per the Configuration docs below
> source .dev.env
> swdocs serve

Configuration

We provide defaults in the const block of main.go, you can override those with environment variables.

An usual way to set environment variables is via your systemd file or a .env. Here is an example of overridding every config.

> cat .dev.env
# File for the sqlite database.
export SWDOCS_DB_PATH='/tmp/swdocs.db'
# Where the contents of the `templates/` folder should be.
export SWDOCS_TEMPLATES_PATH='/tmp/templates'
# Port to run the web app at.
export SWDOCS_PORT='8087'
# Address the web app runs at.
export SWDOCS_HTTP_ADDR='http://localhost'
# Log level of the web app and CLI.
export SWDOCS_LOGLEVEL='debug'

Creating and updating a SwDoc

# Skeleton creates the skeleton of a JSON file for you to apply later.
> swdocs bootstrap rabbitmq
rabbitmq.json file created

# Apply either creates or updates an entry from a JSON file.
> swdocs apply rabbitmq.json

# By default apply will use the process owner username
# You can override it too for CIs 
# (Say from jenkins you parse the username from the commit metadata)
> swdocs apply rabbitmq.json --user ken

Getting and listing SwDocs

# List every SwDoc in the database.
> swdocs list

# List every SwDoc in the database containing the word rabbit.
> swdocs list --filter rabbit%

# Get the URLs for a swdoc from the terminal
> swdocs get rabbitmq

# Or the JSON
> swdocs get rabbitmq --format json

Deleting a SwDoc

> swdocs delete rabbitmq

SwDoc definition

The structs are defined in model.go, an example of a JSON to be inserted is

{
    "name": "rabbitmq",
    "description": "A broker for your messages! AMQP!",
      "sections": [
        {
            "header": "Guides",
            "links": [
                {
                    "url": "https://www.rabbitmq.com/getstarted.html",
                    "description": "Official get started, great guide!"
                }
            ]
        }
      ]
  }

Working with sqlite

The database gets created the first time the program runs.

> sqlite3 /tmp/swdocs.sqlite
>> .tables
>> .schema swdocs

You likely want to backup your .sqlite file periodically!

Screenshots

This is what the UI looks like with a single swdoc on it from the tests

Releasing

We pack the binary and the templates and upload to the releases page of github for the tag!

export RELEASE_TAG=1.0.0
> git tag RELEASE_TAG -m"a release fixing something"
> git push origin main --tags
> tar -czvf swdocs-$RELEASE_TAG.tar.gz swdocs home.gohtml search.gohtml swdoc.gohtml

# Upload the .tar.gz to github