commit fa4f2d9ab434095c49c4b794866048092b982861
parent 76681ee798b81e562ef935e36caab32e403b8964
Author: Daniel Moch <daniel@danielmoch.com>
Date: Thu, 30 Aug 2018 20:26:01 -0400
Add first draft of documentation
Diffstat:
7 files changed, 368 insertions(+), 315 deletions(-)
diff --git a/README.md b/README.md
@@ -1,307 +0,0 @@
-nncli
-=====
-
-
-[](https://pypi.org/project/nncli/)
-
-NextCloud Notes Command Line Interface
-
-nncli is a Python application that gives you access to your NextCloud
-Notes account via the command line. It's a "hard" fork of
-[sncli](https://github.com/insanum/sncli). You can access your notes via
-a customizable console GUI that implements vi-like keybinds or via a
-simple command line interface that you can script.
-
-Notes can be viewed/created/edited in *both an* **online** *and*
-**offline** *mode*. All changes are saved to a local cache on disk and
-automatically sync'ed when nncli is brought online.
-
-**Pull requests are welcome!**
-
-Check your OS distribution for installation packages.
-
-### Requirements
-
-* [Python 3](http://python.org)
-* [Urwid](http://urwid.org) Python 3 module
-* [Requests](https://requests.readthedocs.org/en/master/) Python 3
- module
-* A love for the command line!
-
-### Installation
-
-* Via pip (latest release):
- - `pip3 install nncli`
-* Manually:
- - Clone this repository to your hard disk: `git clone
- https://github.com/djmoch/nncli.git`
- - Install _nncli_: `python3 setup.py install`
-* Development:
- - Clone the repo
- - Install Pipenv: `pip install pipenv`
- - Stand up development environment: `pipenv install --dev`
-
-### Features
-
-* Console GUI
- - full two-way sync with NextCloud Notes performed dynamically in the
- background
- - all actions logged and easily reviewed
- - list note titles (configurable format w/ title, date, flags, category,
- keys, etc)
- - sort notes by date, alpha by title, category, favorite on top
- - search for notes using a Google style search pattern or Regular
- Expression
- - view note contents and meta data
- - pipe note contents to external command
- - create and edit notes (using your editor)
- - edit note category
- - delete notes
- - favorite/unfavorite notes
- - vi-like keybinds (fully configurable)
- - Colors! (fully configurable)
-* Command Line (scripting)
- - force a full two-way sync with NextCloud Notes
- - all actions logged and easily reviewed
- - list note titles and keys
- - search for notes using a Google style search pattern or Regular
- Expression
- - dump note contents
- - create a new note (via stdin or editor)
- - import a note with raw json data (stdin or editor)
- - edit a note (via editor)
- - delete a note
- - favorite/unfavorite a note
- - view and edit note category
-
-### HowTo
-
-```
-Usage:
- nncli [OPTIONS] [COMMAND] [COMMAND_ARGS]
-
- OPTIONS:
- -h, --help - usage help
- -v, --verbose - verbose output
- -n, --nosync - don't perform a server sync
- -r, --regex - search string is a regular expression
- -k <key>, --key=<key> - note key
- -t <title>, --title=<title> - title of note for create (cli mode)
- -c <file>, --config=<file> - config file to read from
- --version - version information
-
- COMMANDS:
- <none> - console gui mode when no command specified
- sync - perform a full sync with the server
- list [search_string] - list notes (refined with search string)
- export [search_string] - export notes in JSON (refined with search string)
- dump [search_string] - dump notes (refined with search string)
- create [-] - create a note ('-' content from stdin)
- import [-] - import a note in JSON format ('-' JSON from stdin)
- export - export a note in JSON format (specified by <key>)
- dump - dump a note (specified by <key>)
- edit - edit a note (specified by <key>)
- delete - delete a note (specified by <key>)
- < favorite | unfavorite > - favorite/unfavorite a note (specified by <key>)
- cat get - retrieve the category from a note (specified by <key>)
- cat set <category> - set the category for a note (specified by <key>)
- cat rm - remove category from a note (specified by <key>)
-```
-
-#### Configuration
-
-The current NextCloud Notes API does not support oauth authentication so
-your NextCloud Notes account password must be stored someplace
-accessible to nncli. Use of the `cfg_nn_password_eval` option is
-recommended (see below).
-
-nncli pulls in configuration from the `config` file located in the
-standard location for your platform. At the very least, the following
-example `config` will get you going (using your account information):
-
-```
-[nncli]
-cfg_nn_username = lebowski@thedude.com
-cfg_nn_password = nihilist
-cfg_nn_host = nextcloud.thedude.com
-```
-
-Start nncli with no arguments which starts the console GUI mode. nncli
-will begin to sync your existing notes and you'll see log messages at
-the bottom of the console. You can view these log messages at any time
-by pressing the `l` key.
-
-View the help by pressing `h`. Here you'll see all the keybinds and
-configuration items. The middle column shows the config name that can be
-used in your `config` to override the default setting.
-
-See example configuration file below for more notes.
-
-```
-[nncli]
-cfg_nn_username = lebowski@thedude.com
-cfg_nn_password = nihilist
-cfg_nn_host = nextcloud.thedude.com
-
-# as an alternate to cfg_nn_password you could use the following config item
-# any shell command can be used; its stdout is used for the password
-# trailing newlines are stripped for ease of use
-# note: if both password config are given, cfg_nn_password will be used
-cfg_nn_password_eval = gpg --quiet --for-your-eyes-only --no-tty --decrypt ~/.nncli-pass.gpg
-
-# see http://urwid.org/manual/userinput.html for examples of more key
-# combinations
-kb_edit_note = space
-kb_page_down = ctrl f
-
-# note that values must not be quoted
-clr_note_focus_bg = light blue
-
-# if this editor config value is not provided, the $EDITOR env var will be
-# used instead
-# warning: if neither $EDITOR or cfg_editor is set, it will be impossible to
-# edit notes
-cfg_editor = nvim
-
-# alternatively, {fname} and/or {line} are substituted with the filename and
-# current line number in nncli's pager.
-# If {fname} isn't supplied, the filename is simply appended.
-# examples:
-cfg_editor = nvim {fname} +{line}
-cfg_editor = nano +{line}
-
-# this is also supported for the pager:
-cfg_pager = less -c +{line} -N {fname}
-```
-
-#### Note Title Format
-
-The format of each line in the note list is driven by the
-`cfg_format_note_title` config item. Various formatting tags are
-supported for dynamically building the title string. Each of these
-formatting tags supports a width specifier (decimal) and a left
-justification (-) like that supported by printf:
-
-```
-%F - flags (fixed 5 char width)
- X - needs sync
- * - favorited
-%T - category
-%D - date
-%N - title
-```
-
-The default note title format pushes the note category to the far right of
-the terminal and left justifies the note title after the date and flags:
-
-``` cfg_format_note_title = '[%D] %F %-N %T' ```
-
-Note that the `%D` date format is further defined by the strftime format
-specified in `cfg_format_strftime`.
-
-#### Colors
-
-nncli utilizes the Python [Uwrid](http://urwid.org) module to implement
-the console user interface.
-
-At this time, nncli does not yet support 256-color terminals and is
-limited to just 16-colors. Color names that can be specified in the
-`config` file are listed
-[here](http://urwid.org/manual/displayattributes.html#standard-foreground-colors).
-
-### Searching
-
-nncli supports two styles of search strings. First is a Google style
-search string and second is a Regular Expression.
-
-A Google style search string is a group of tokens (separated by spaces)
-with an implied *AND* between each token. This style search is case
-insensitive. For example:
-
-`/category:category1 category:category2 word1 "word2 word3" category:category3`
-
-Regular expression searching also supports the use of flags (currently
-only case-insensitive) by adding a final forward slash followed by the
-flags. The following example will do a case-insensitive search for
-`something`:
-
-`(regex) /something/i`
-
-### Creating from command line
-
-```
-# create a new note and open in editor
-nncli create
-
-# create a new note with contents of stdin
-echo 'hi' | nncli create -
-```
-
-### Importing
-
-nncli can import notes from raw json data (via stdin or editor). For
-example:
-
-`echo '{"category":"testing","content":"New note!"}' | nncli import - `
-
-Allowed fields are `content`, `category`, `favorite`, and `modified`
-
-### Exporting
-
-nncli can export notes as json data to stdout. Example:
-
-```
-# export a single note by id
-nncli -k somekeyid export
-
-# export all notes
-nncli export
-
-# export notes matching search string
-nncli [-r] export some search keywords or regex
-```
-
-Note that nncli still stores all the notes data in the directory
-specified by `cfg_db_path`, so for easy backups, it may be
-easier/quicker to simply backup this entire directory.
-
-### Category
-
-Note category can be modified directly from the command line. Example:
-
-```
-# Retrieve note category (e.g. "category1")
-nncli -k somekeyid cat get
-# Returns "category1"
-
-# Add a category to a note, overwriting any existing one
-nncli -k somekeyid cat set "category3"
-# Now tagged as "category3"
-
-# Remove a category from a note
-nncli -k somekeyid cat rm
-# Note now has no category
-```
-### Tricks
-
-Advanced text editors usually tailor their behavior based on the file
-type being edited. For such editors, notes opened through nncli should
-be treated as Markdown by default. However, you can change this
-on a per-note basis through the use of modelines. In Vim, for instance,
-a modeline is a comment line conforming to the pattern below.
-
-``` ; vim:ft=votl ```
-
-Now when I edit this note Vim will automatically load the votl plugin.
-Lots of possibilities here...
-
-### Thanks
-
-nncli is a fork of [sncli](https://github.com/insanum/sncli) by
-[insanum](https://github.com/insanum). This application further pulls in
-and uses modified versions of the
-[simplenote.py](https://github.com/mrtazz/simplenote.py) module by
-[mrtazz](https://github.com/mrtazz) and the
-[notes_db.py](https://github.com/cpbotha/nvpy/blob/master/nvpy/notes_db.py)
-module from [nvpy](https://github.com/cpbotha/nvpy) by
-[cpbotha](https://github.com/cpbotha).
diff --git a/README.rst b/README.rst
@@ -0,0 +1,119 @@
+nncli is a Python application that gives you access to your NextCloud
+Notes account via the command line. It's a "hard" fork of
+sncli_. You can access your notes via
+a customizable console GUI that implements vi-like keybinds or via a
+simple command line interface that you can script.
+
+Notes can be viewed/created/edited in *both an* **online** *and*
+**offline** *mode*. All changes are saved to a local cache on disk and
+automatically sync'ed when nncli is brought online.
+
+More detailed documentation can be found on the documentation_ page.
+
+Requirements
+------------
+
+- `Python 3`_
+
+- Urwid_ Python 3 module
+
+- Requests_ Python 3 module
+
+- A love for the command line!
+
+Installation
+------------
+
+- Via pip (latest release):
+
+ - ``pip3 install nncli``
+
+- Manually:
+
+ - Clone this repository to your hard disk: ``git clone
+ https://github.com/djmoch/nncli.git``
+
+ - Install nncli: ``python3 setup.py install``
+
+- Development:
+
+ - Clone the repo
+
+ - Install Pipenv: ``pip install pipenv``
+
+ - Stand up development environment: ``pipenv install --dev``
+
+Features
+--------
+
+- Console GUI
+
+ - full two-way sync with NextCloud Notes performed dynamically in the
+ background
+
+ - all actions logged and easily reviewed
+
+ - list note titles (configurable format w/ title, date, flags, category,
+ keys, etc)
+
+ - sort notes by date, alpha by title, category, favorite on top
+
+ - search for notes using a Google style search pattern or Regular
+ Expression
+
+ - view note contents and meta data
+
+ - pipe note contents to external command
+
+ - create and edit notes (using your editor)
+
+ - edit note category
+
+ - delete notes
+
+ - favorite/unfavorite notes
+
+ - vi-like keybinds (fully configurable)
+
+ - Colors! (fully configurable)
+
+- Command Line (scripting)
+
+ - force a full two-way sync with NextCloud Notes
+
+ - all actions logged and easily reviewed
+
+ - list note titles and keys
+
+ - search for notes using a Google style search pattern or Regular
+ Expression
+
+ - dump note contents
+
+ - create a new note (via stdin or editor)
+
+ - import a note with raw json data (stdin or editor)
+
+ - edit a note (via editor)
+
+ - delete a note
+
+ - favorite/unfavorite a note
+
+ - view and edit note category
+
+
+Thanks
+------
+
+nncli is a fork of sncli_ by insanum. This application further pulls in
+and uses modified versions of the simplenote.py_ module by mrtazz and
+the notes_db.py module from nvpy_ by cpbotha.
+
+.. _sncli: https://github.com/insanum/sncli
+.. _Python 3: http://python.org
+.. _Urwid: http://urwid.org
+.. _Requests: https://requests.readthedocs.org/en/master
+.. _simplenote.py: https://github.com/mrtazz/simplenote.py
+.. _nvpy: https://github.com/cpbotha/nvpy
+.. _documentation: https://nncli.readthedocs.io/en/latest
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -24,9 +24,9 @@
author = 'Daniel Moch'
# The short X.Y version
-version = ''
+version = nnotes_cli.__version__
# The full version, including alpha/beta/rc tags
-release = '0.1.3'
+release = nnotes_cli.__version__
# -- General configuration ---------------------------------------------------
@@ -76,7 +76,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'alabaster'
+html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -0,0 +1,106 @@
+Configuration
+=============
+
+The current NextCloud Notes API does not support oauth authentication so
+your NextCloud Notes account password must be stored someplace
+accessible to nncli. Use of the ``cfg_nn_password_eval`` option is
+recommended (see below).
+
+nncli pulls in configuration from the ``config`` file located in the
+standard location for your platform. At the very least, the following
+example ``config`` will get you going (using your account information)::
+
+ [nncli]
+ cfg_nn_username = lebowski@thedude.com
+ cfg_nn_password = nihilist
+ cfg_nn_host = nextcloud.thedude.com
+
+Start nncli with no arguments which starts the console GUI mode. nncli
+will begin to sync your existing notes and you'll see log messages at
+the bottom of the console. You can view these log messages at any time
+by pressing the ``l`` key.
+
+View the help by pressing ``h``. Here you'll see all the keybinds and
+configuration items. The middle column shows the config name that can be
+used in your ``config`` to override the default setting.
+
+See example configuration file below for more notes.
+
+::
+
+ [nncli]
+ cfg_nn_username = lebowski@thedude.com
+ cfg_nn_password = nihilist
+ cfg_nn_host = nextcloud.thedude.com
+
+ # as an alternate to cfg_nn_password you could use the following config item
+ # any shell command can be used; its stdout is used for the password
+ # trailing newlines are stripped for ease of use
+ # note: if both password config are given, cfg_nn_password will be used
+ cfg_nn_password_eval = gpg --quiet --for-your-eyes-only --no-tty --decrypt ~/.nncli-pass.gpg
+
+ # see http://urwid.org/manual/userinput.html for examples of more key
+ # combinations
+ kb_edit_note = space
+ kb_page_down = ctrl f
+
+ # note that values must not be quoted
+ clr_note_focus_bg = light blue
+
+ # if this editor config value is not provided, the $EDITOR env var will be
+ # used instead
+ # warning: if neither $EDITOR or cfg_editor is set, it will be impossible to
+ # edit notes
+ cfg_editor = nvim
+
+ # alternatively, {fname} and/or {line} are substituted with the filename and
+ # current line number in nncli's pager.
+ # If {fname} isn't supplied, the filename is simply appended.
+ # examples:
+ cfg_editor = nvim {fname} +{line}
+ cfg_editor = nano +{line}
+
+ # this is also supported for the pager:
+ cfg_pager = less -c +{line} -N {fname}
+
+.. index:: single: configuration; gui titles
+
+Note Title Format
+-----------------
+
+The format of each line in the note list is driven by the
+``cfg_format_note_title`` config item. Various formatting tags are
+supported for dynamically building the title string. Each of these
+formatting tags supports a width specifier (decimal) and a left
+justification (-) like that supported by printf::
+
+ %F - flags (fixed 5 char width)
+ X - needs sync
+ * - favorited
+ %T - category
+ %D - date
+ %N - title
+
+The default note title format pushes the note category to the far right of
+the terminal and left justifies the note title after the date and
+flags::
+
+ cfg_format_note_title = '[%D] %F %-N %T'
+
+Note that the ``%D`` date format is further defined by the strftime format
+specified in ``cfg_format_strftime``.
+
+.. index:: single: configuration; gui colors
+
+Colors
+------
+
+nncli utilizes the Python Urwid_ module to implement the console user
+interface.
+
+At this time, nncli does not yet support 256-color terminals and is
+limited to just 16-colors. Color names that can be specified in the
+``config`` file are listed here_.
+
+.. _Urwid: http://urwid.org
+.. _here: http://urwid.org/manual/displayattributes.html#standard-foreground-colors
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,18 +3,19 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to nncli's documentation!
-=================================
+NextCloud Notes Command Line Interface
+======================================
.. toctree::
:maxdepth: 2
:caption: Contents:
+ configuration
+ usage
Indices and tables
==================
* :ref:`genindex`
-* :ref:`modindex`
* :ref:`search`
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -0,0 +1,134 @@
+Usage
+=====
+
+.. index:: single: usage
+
+::
+
+ nncli [OPTIONS] [COMMAND] [COMMAND_ARGS]
+
+ OPTIONS:
+ -h, --help - usage help
+ -v, --verbose - verbose output
+ -n, --nosync - don't perform a server sync
+ -r, --regex - search string is a regular expression
+ -k <key>, --key=<key> - note key
+ -t <title>, --title=<title> - title of note for create (cli mode)
+ -c <file>, --config=<file> - config file to read from
+ --version - version information
+
+ COMMANDS:
+ <none> - console gui mode when no command specified
+ sync - perform a full sync with the server
+ list [search_string] - list notes (refined with search string)
+ export [search_string] - export notes in JSON (refined with search string)
+ dump [search_string] - dump notes (refined with search string)
+ create [-] - create a note ('-' content from stdin)
+ import [-] - import a note in JSON format ('-' JSON from stdin)
+ export - export a note in JSON format (specified by <key>)
+ dump - dump a note (specified by <key>)
+ edit - edit a note (specified by <key>)
+ delete - delete a note (specified by <key>)
+ < favorite | unfavorite > - favorite/unfavorite a note (specified by <key>)
+ cat get - retrieve the category from a note (specified by <key>)
+ cat set <category> - set the category for a note (specified by <key>)
+ cat rm - remove category from a note (specified by <key>)
+
+.. index:: single: searching
+
+Searching
+---------
+
+nncli supports two styles of search strings. First is a Google style
+search string and second is a Regular Expression.
+
+A Google style search string is a group of tokens (separated by spaces)
+with an implied *AND* between each token. This style search is case
+insensitive. For example::
+
+ /category:category1 category:category2 word1 "word2 word3" category:category3
+
+Regular expression searching also supports the use of flags (currently
+only case-insensitive) by adding a final forward slash followed by the
+flags. The following example will do a case-insensitive search for
+``something``::
+
+ (regex) /something/i
+
+.. index:: single: command line; creating
+
+Creating from command line
+--------------------------
+
+::
+ # create a new note and open in editor
+ nncli create
+
+ # create a new note with contents of stdin
+ echo 'hi' | nncli create -
+
+.. index:: single: command line; importing
+
+Importing
+---------
+
+nncli can import notes from raw json data (via stdin or editor). For
+example::
+
+ echo '{"category":"testing","content":"New note!"}' | nncli import -
+
+Allowed fields are ``content``, ``category``, ``favorite``, and ``modified``
+
+.. index:: single: command line; exporting
+
+Exporting
+---------
+
+nncli can export notes as json data to stdout. Example::
+
+ # export a single note by id
+ nncli -k somekeyid export
+
+ # export all notes
+ nncli export
+
+ # export notes matching search string
+ nncli [-r] export some search keywords or regex
+
+Note that nncli still stores all the notes data in the directory
+specified by ``cfg_db_path``, so for easy backups, it may be
+easier/quicker to simply backup this entire directory.
+
+.. index:: single: command line; categories
+
+Categories
+----------
+
+Note category can be modified directly from the command line. Example::
+
+ # Retrieve note category (e.g. "category1")
+ nncli -k somekeyid cat get
+ # Returns "category1"
+
+ # Add a category to a note, overwriting any existing one
+ nncli -k somekeyid cat set "category3"
+ # Now tagged as "category3"
+
+ # Remove a category from a note
+ nncli -k somekeyid cat rm
+ # Note now has no category
+
+.. index:: single: tricks
+
+Tricks
+------
+
+Advanced text editors usually tailor their behavior based on the file
+type being edited. For such editors, notes opened through nncli should
+be treated as Markdown by default. However, you can change this
+on a per-note basis through the use of modelines. In Vim, for instance,
+a modeline is a comment line conforming to the pattern below::
+
+ :: vim: ft=rst
+
+Now when you edit this note Vim will automatically load the rst plugin.
diff --git a/setup.py b/setup.py
@@ -31,14 +31,14 @@
deps = ['urwid', 'requests', 'appdirs']
test_deps = ['pytest', 'pytest-cov', 'pytest-runner', 'pytest-mock']
-with open("README.md", "r") as fh:
+with open("README.rst", "r") as fh:
long_description = fh.read()
setup(
name=nnotes_cli.__productname__,
description=nnotes_cli.__description__,
long_description=long_description,
- long_description_content_type="text/markdown",
+ long_description_content_type="text/x-rst",
author=nnotes_cli.__author__,
author_email=nnotes_cli.__author_email__,
url=nnotes_cli.__url__,
