.. image:: https://travis-ci.org/noqqe/cmddocs.svg?branch=master :target: https://travis-ci.org/noqqe/cmddocs
.. image:: https://codecov.io/gh/noqqe/cmddocs/branch/master/graph/badge.svg :target: https://codecov.io/gh/noqqe/cmddocs
cmddocs
cmddocs is an interactive commandline wiki. It
lets you easily maintain your docs/cheetsheets/notes using:
- Plain Text Files
- Write
markdownin 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 <http://www.mutt.org>,
taskwarrior <http://taskwarrior.org>,
jrnl <http://maebert.github.io/jrnl/>,
weechat <http://weechat.org> 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 <https://github.com/lepture/mistune>__ lexer to
wrap markdown with ansi control sequences instead of html tags.
It looks something like this.
.. image:: https://raw.github.com/noqqe/cmddocs/master/cmddocs-md2ascii.png
Demo
To give you an idea what it looks/feels like I created a short terminal recording.
asciinema cmddocs demo <https://asciinema.org/a/15168>__
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 = [email protected]
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: [email protected]
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_.
.. _Changelog: https://github.com/noqqe/cmddocs/blob/master/CHANGELOG.rst
License
See License_.
.. _License: https://github.com/noqqe/cmddocs/blob/master/License.txt