nncli

NextCloud Notes Command Line Interface
git clone git://git.danielmoch.com/nncli.git
Log | Files | Refs | LICENSE

commit 06d55e9210414abebe71f79895b287c95c0942a8
parent 0fda166b2c534d50f6aa9d2d75f5ff476164fb72
Author: Daniel Moch <daniel@danielmoch.com>
Date:   Sat,  1 Sep 2018 17:04:30 -0400

Document config file general options

Diffstat:
Mdocs/source/conf.py | 13+++++++++++++
Mdocs/source/configuration.rst | 374++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
2 files changed, 355 insertions(+), 32 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py @@ -41,6 +41,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.todo', + 'sphinx.ext.intersphinx', ] # Add any paths that contain templates here, relative to this directory. @@ -159,7 +160,19 @@ # -- Extension configuration ------------------------------------------------- +# -- Options for intersphinx extension --------------------------------------- +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + # -- Options for todo extension ---------------------------------------------- # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True + +# -- Extension interface ----------------------------------------------------- +def setup(app): + from sphinx.ext.autodoc import cut_lines + from sphinx.util.docfields import GroupedField + app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) + app.add_object_type('confval', 'confval', + objname='configuration value', + indextemplate='pair: %s; configuration value') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst @@ -6,7 +6,7 @@ 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). +recommended (see :ref:`config-file`). .. _config-file: @@ -14,8 +14,347 @@ Configuration File ------------------ 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): +standard location for your platform. + +.. todo:: Add platform-specific location information + +The following directives are accepted within the ``config`` file: + +General Options +~~~~~~~~~~~~~~~ + +.. confval:: cfg_nn_host + + Sets the URL of the NextCloud instance to connect to. + + Required. + +.. confval:: cfg_nn_username + + The user name to log in as. + + Required. + +.. confval:: cfg_nn_password + + The password to use for log in. + + Optional. Overrides :confval:`cfg_nn_password_eval` if both are + specified. + +.. confval:: cfg_nn_password_eval + + A command to run to retrieve the password. The command should return + the password on ``stdout``. + + Optional. Required if :confval:`cfg_nn_password` is not specified. + +.. confval:: cfg_db_path + + Specifies the path of the local notes cache. + + Optional. Default value: + + - Windows: ``%USERPROFILE%\AppData\Local\djmoch\nncli\Cache`` + + - macOS: ``~/Library/Caches/nncli`` + + - \*nix: ``~/.cache/nncli`` + +.. confval:: cfg_search_categories + + Set to ``yes`` to include categories in searches. Otherwise set to + ``no``. + + Optional. Default value: ``yes`` + +.. confval:: cfg_sort_mode + + Sets how notes are sorted in the console GUI. Set to ``date`` + to have them sorted by date (newest on top). Set to ``alpha`` to have + them sorted alphabetically. + + Optional. Default value: ``date`` + +.. confval:: cfg_favorite_ontop + + Determines whether notes marked as favorite are sorted on top. + + Optional. Default value: ``yes`` + +.. confval:: cfg_tabstop + + Sets the width of a tabstop character. + + Optional. Default value: ``4`` + +.. confval:: cfg_format_strftime + + Sets the format of the note timestamp (``%D``) in the note title. The + format values are the specified in :py:func:`time.strftime`. + + Optional. Default value: ``%Y/%m/%d`` + +.. confval:: cfg_format_note_title + + Sets the format of each line in the console GUI note list. 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: + + .. code-block:: none + + %F - flags (fixed 2 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. + + Optional. Default value: ``[%D] %F %-N %T`` + + Note that the ``%D`` date format is further defined by the strftime + format specified in :confval:`cfg_format_strftime`. + +.. confval:: cfg_status_bar + + Sets whether or not the status bar is visible at the top of the + console GUI. + + Optional. Default value: ``yes`` + +.. confval:: cfg_editor + + Sets the command to run when opening a note for editing. The special + values ``{fname}`` and ``{line}`` can be used to specify respectively + the file name and line number to pass to the command. + + Optional. Default value: ``$EDITOR`` if defined in the user's + environment, else ``vim {fname} +{line}``. + +.. confval:: cfg_pager + + Sets the command to run when opening a note for viewing in an + external pager. + + Optional. Default value: ``$PAGER`` if defined in the user's + environment, else ``less -c``. + +.. confval:: cfg_diff + + .. todo:: Remove ``cfg_diff`` + +.. confval:: cfg_max_logs + + Sets the number of log events to display together in the consule GUI + footer. + + Optional. Default value: ``5`` + +.. confval:: cfg_log_timeout + + Sets the rate to poll for log events. Unit is seconds. + + Optional. Default value: ``5`` + +.. confval:: cfg_log_reversed + + Sets whether or not the log is displayed in reverse-chronological + order. + + Optional. Default value: ``yes`` + +.. confval:: cfg_tempdir + + Sets a directory path to store temporary files in. ``nncli`` uses + :func:`tempfile.mkstemp` under the hood, and the most nuanced + description of how this value is used can be found in the discussion + of the ``dir`` keyword argument there. Basically you should not + specify this if you want to use the platform-standard temporary + folder. + + Optional. Default value: *[blank]* + +Keybindings +~~~~~~~~~~~ + +.. confval:: kb_help + +.. confval:: kb_quit + +.. confval:: kb_sync + +.. confval:: kb_down + +.. confval:: kb_up + +.. confval:: kb_page_down + +.. confval:: kb_page_up + +.. confval:: kb_half_page_down + +.. confval:: kb_half_page_up + +.. confval:: kb_bottom + +.. confval:: kb_top + +.. confval:: kb_status + +.. confval:: kb_create_note + +.. confval:: kb_edit_note + +.. confval:: kb_view_note + +.. confval:: kb_view_note_ext + +.. confval:: kb_view_note_json + +.. confval:: kb_pipe_note + +.. confval:: kb_view_next_note + +.. confval:: kb_view_prev_note + +.. confval:: kb_view_log + +.. confval:: kb_tabstop2 + +.. confval:: kb_tabstop4 + +.. confval:: kb_tabstop8 + +.. confval:: kb_search_gstyle + +.. confval:: kb_search_regex + +.. confval:: kb_search_prev_gstyle + +.. confval:: kb_search_prev_regex + +.. confval:: kb_search_next + +.. confval:: kb_search_prev + +.. confval:: kb_clear_search + +.. confval:: kb_sort_date + +.. confval:: kb_sort_alpha + +.. confval:: kb_sort_categories + +.. confval:: kb_note_delete + +.. confval:: kb_note_favorite + +.. confval:: kb_note_category + +.. confval:: kb_copy_note_text + +Colors +~~~~~~ + +.. confval:: clr_default_fg + +.. confval:: clr_default_bg + +.. confval:: clr_status_bar_fg + +.. confval:: clr_status_bar_bg + +.. confval:: clr_log_fg + +.. confval:: clr_log_bg + +.. confval:: clr_user_input_bar_fg + +.. confval:: clr_user_input_bar_bg + +.. confval:: clr_note_focus_fg + +.. confval:: clr_note_focus_bg + +.. confval:: clr_note_title_day_fg + +.. confval:: clr_note_title_day_bg + +.. confval:: clr_note_title_week_fg + +.. confval:: clr_note_title_week_bg + +.. confval:: clr_note_title_month_fg + +.. confval:: clr_note_title_month_bg + +.. confval:: clr_note_title_year_fg + +.. confval:: clr_note_title_year_bg + +.. confval:: clr_note_title_ancient_fg + +.. confval:: clr_note_title_ancient_bg + +.. confval:: clr_note_date_fg + +.. confval:: clr_note_date_bg + +.. confval:: clr_note_flags_fg + +.. confval:: clr_note_flags_bg + +.. confval:: clr_note_category_fg + +.. confval:: clr_note_category_bg + +.. confval:: clr_note_content_fg + +.. confval:: clr_note_content_bg + +.. confval:: clr_note_content_focus_fg + +.. confval:: clr_note_content_focus_bg + +.. confval:: clr_note_content_old_fg + +.. confval:: clr_note_content_old_bg + +.. confval:: clr_note_content_old_focus_fg + +.. confval:: clr_note_content_old_focus_bg + +.. confval:: clr_help_focus_fg + +.. confval:: clr_help_focus_bg + +.. confval:: clr_help_header_fg + +.. confval:: clr_help_header_bg + +.. confval:: clr_help_config_fg + +.. confval:: clr_help_config_bg + +.. confval:: clr_help_value_fg + +.. confval:: clr_help_value_bg + +.. confval:: clr_help_descr_fg + +.. confval:: clr_help_descr_bg + +Examples +-------- + +At the very least, the following example ``config`` will get you going +(using your account information): .. code-block:: ini @@ -72,35 +411,6 @@ See example configuration file below for more notes. ; 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: - -.. code-block:: ini - - 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