GitHub - noqqe/cmddocs: An interactive commandline interface for your personal docs using python, Cmd, git and markdown

cmddocs

cmddocs is an interactive commandline wiki. It lets you easily maintain your docs/cheetsheets/notes using:

• Plain Text Files
• Write markdown in your local Editor
• View in your local Pager
• Versioning with git

cmddocs is like a framework around your plaintext files.

Why ?

I kind of started cmddocs because I couldn't find something like this on the internet. Here's my usecase. Im working as a DevOps guy being in touch with various types of software, languages, tools, operating systems and databases. To remember all those things I need a place to store commands, workflows and short howtos.

Most of the software I use (and love) runs on a OpenBSD Box on the internet and are commandline-based. These are mutt, taskwarrior, jrnl, weechat and so on...But i was missing a tool for documentation.

After switching to just plaintext files using vim and git it was also a bit annoying. So I wrote cmddocs to make it easier for me to handle my plaintext files.

Markdown Rendering

cmddocs uses the mistune lexer to wrap markdown with ansi control sequences instead of html tags.

It looks something like this.

Demo

To give you an idea what it looks/feels like I created a short terminal recording.

asciinema cmddocs demo

Installation

pip install cmddocs

Also make sure you have tree installed.

Configuration

Create .cmddocsrc file in your $HOME with the following content (adjust to your needs):

[General]
Datadir = /home/noqqe/Docs
Default_Commit_Message = small changes
Excludedir = .git/
Editor = /usr/local/bin/vim
# EditorFlags = -C
Pager = /usr/bin/less
PagerFlags = -fr
Prompt = cmddocs>
Promptcolor = 37
Intro_Message = cmddocs - press ? for help
Mail = mail@example.org
Default_Extension = md

[Colors]
Header12 = 37
Header345 = 37
Codeblock = 92

The only required option is "Datadir", everything else will be guessed or defaults to a sane default value. Once you start cmddocs.py the CLI will be shown. Use help for commands.

Quick Start

At first, create a very minimal config, like

[General]
Datadir = /home/noqqe/Docs
Editor = /usr/local/bin/vim
Pager = /usr/bin/less

Then you can start using cmddocs.

$ cmddocs
cmddocs - press ? for help
cmddocs> help

Documented commands (type help <topic>):
========================================
EOF  delete  e     help  list  mail  pwd     search  undo
cd   diff    edit  info  log   move  revert  stats   version
d    dirs    exit  l     ls    mv    rm      status  view

cmddocs> help l

    Show files in current working dir

cmddocs> help log

    Show git logs of your docs.

    Usage: log                      # default loglines: 10)
           log 20                   # show 20 loglines
           log 20 article           # show log for specific article
           log databases/mongodb 3  # same

Command Documentation

cd

Change directory

Usage:
    cd Programming/
    cd

delete, rm

Delete an article

Usage:
    delete databases/mongodb
    rm databases/mssql

dirs, d

Show directories in current working dir

Usage:
    dirs
    d
    dirs Databases/

e, edit

Edit or create new article.

Usage:
    edit databases/mongodb
    edit intro

list, l, ls

Show files in current working dir

Usage:
    list
    l
    list Databases/

move, mv

Move an article to a new location

Usage:
    move databases/mongodb databases/MongoDB
    move life/foo notes/foo
    mv life/foo notes/foo

view

View an article. Creates temporary file with converted markdown to ansi colored output. Opens your PAGER. (Only less supported atm)

Usage:
    view databases/mongodb
    view intro

mail

Mail an article to a friend

Usage:
    mail databases/mongodb
    Recipient: mail@example.net

    mail programming/r/loops
    mail intro

pwd

Show current directory

Usage:
    pwd

search

Search for keyword in current directory

Usage:
    search mongodb
    search foo

undo, revert

You can revert your changes (use revert from git)

Usage:
    undo HEAD
    undo 355f375

Will ask for confirmation.

diff

Show git diffs between files and commits

Usage:
    diff 7                   # show diff for last 7 changes
    diff 1 article           # show diff for last change to article
    diff                     # show last 5 diffs

info

Show infos for an article

Usage:
    info article
    info Databases/mongodb
    Created: 2014-01-18 11:18:03 +0100
    Updated: 2015-10-23 14:14:44 +0200
    Commits: 26
    Lines: 116
    Words: 356
    Characters: 2438

log

Show git logs of your docs.

Usage:
    log                      # default loglines: 10)
    log 20                   # show 20 loglines
    log 20 article           # show log for specific article
    log databases/mongodb 3  # same

status

Show git repo status of your docs

Usage:
    status

stats

Calculate some statistics on your docs

Usage:
    stats

exit, EOF

Exit cmddocs

Usage:
    exit

help

List available commands with "help" or detailed help with "help cmd".

version

Show version of cmddocs

Usage:
    version

Changelog

See Changelog.

License

See License.