https://github.com/noqqe/cmddocs
An interactive commandline interface for your personal docs using python, Cmd, git and markdown
https://github.com/noqqe/cmddocs
cmdi command-line docs markdown notes python wiki
Last synced: 3 months ago
JSON representation
An interactive commandline interface for your personal docs using python, Cmd, git and markdown
- Host: GitHub
- URL: https://github.com/noqqe/cmddocs
- Owner: noqqe
- License: mit
- Created: 2015-01-04T10:17:43.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2021-02-01T07:07:19.000Z (over 5 years ago)
- Last Synced: 2026-01-05T16:47:16.653Z (6 months ago)
- Topics: cmdi, command-line, docs, markdown, notes, python, wiki
- Language: Python
- Size: 232 KB
- Stars: 64
- Watchers: 2
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE.txt
Awesome Lists containing this project
README
.. 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 ``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.
.. 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 `__
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 ):
========================================
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