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 <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 = 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_.

.. _Changelog: https://github.com/noqqe/cmddocs/blob/master/CHANGELOG.rst

License
-------

See License_.

.. _License: https://github.com/noqqe/cmddocs/blob/master/License.txt

