Browse Source

Start writing a proper documentation.

The README is not enough, Pebble needs a proper manual.
Damien Goutte-Gattat 2 years ago
5 changed files with 273 additions and 0 deletions
  1. +56
  2. +26
  3. +70
  4. +114
  5. +7

+ 56
- 0
docs/ View File

@ -0,0 +1,56 @@
# -*- coding: utf-8 -*-
# -- General configuration ------------------------------------------------
source_suffix = '.rst'
master_doc = 'index'
copyright = u'2019 Damien Goutte-Gattat'
author = u'Damien Goutte-Gattat <>'
language = 'en'
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'
# -- Options for HTML output ----------------------------------------------
html_theme = 'alabaster'
html_static_path = ['_static']
# -- Options for LaTeX output ---------------------------------------------
latex_engine = 'lualatex'
latex_elements = {
'papersize': 'a4paper',
'pointsize': '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Pebble.tex', u'Pebble Documentation',
u'Damien Goutte-Gattat', 'manual'),
# -- Options for manual page output ---------------------------------------
man_pages = [
(master_doc, 'pebble', u'Pebble Documentation',
[author], 1)
# -- Options for Texinfo output -------------------------------------------
texinfo_documents = [
(master_doc, 'Pebble', u'Pebble Documentation',
author, 'Pebble', 'One line description of project.',

+ 26
- 0
docs/index.rst View File

@ -0,0 +1,26 @@
.. Pebble documentation master file, created by
sphinx-quickstart on Fri Jan 25 23:43:41 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Pebble Manual
Pebble is a command-line client for the `Passman`_ passwords manager for
`Nextcloud`_. It allows users to view and edit the contents of a
Passman vault from the command line and with their favorite text editor
rather than from a web browser.
.. _Passman:
.. _Nextcloud:
Pebble is free software, published under the GNU General Public License.
It is written in Python and should work with both Python 2.7 and Python
.. toctree::
:maxdepth: 2

+ 70
- 0
docs/install.rst View File

@ -0,0 +1,70 @@
Installing Pebble
Installing from PyPI
Packages for Pebble are published on the `Python Package Index`_ under
the name ``incenp.pebble``. To install the latest version from PyPI:
.. _Python Package Index:
.. code-block:: console
$ pip install -U incenp.pebble
Installing from source
You may download a release tarball from the `homepage`_ or from the
`release page`_, and then proceed to a manual installation:
.. _homepage:
.. _release page:
.. code-block:: console
$ tar zxf incenp.pebble-0.4.0.tar.gz
$ cd incenp.pebble-0.4.0
$ python build
$ python install
You may also clone the repository:
.. code-block:: console
$ git clone
and then proceed as above.
Pebble requires the following Python dependencies to work:
* `sjcl <>`_
* `requests <>`_
If you install Pebble from the Python Package Index with `pip` as
described above, those dependencies should be automatically installed if
they are not already available on your system.
Testing the installation
Once installed, Pebble may be invoked from the command line by calling
the ``pbl`` program. You can check whether it has been installed
correctly by running the following command:
.. code-block:: console
$ pbl --version
pbl (Pebble 0.4.0)
Copyright © 2018,2019 Damien Goutte-Gattat
This program is released under the GNU General Public License.
See the COPYING file or <>.

+ 114
- 0
docs/quickstart.rst View File

@ -0,0 +1,114 @@
Getting Started
You need to have Pebble :doc:`installed <install>` with the ``pbl``
program available from the command line.
You also need an account on a Nextcloud instance with the Passman
application installed, and at least one Passman vault created.
Creating a configuration file
Pebble requires a configuration file describing the vault(s) to use and
cannot function properly without one. By default, Pebble will look for a
file named ``config`` under the directory ``$XDG_CONFIG_HOME/pebble``.
A simple configuration file may look like the following:
.. code-block:: ini
user: alice
password: XXXXXX
vault: MyVault
where ```` is the Nextcloud or Owncloud server,
``alice`` is the username of an account on that server, ``XXXXXX`` the
corresponding password, and ``MyVault`` the name of a Passman’s vault.
Listing, searching and viewing credentials
Use the ``list`` command to print the labels for all credentials
stored in the vault:
.. code-block:: console
$ pbl list
Called with one or more parameters, the command will only print
credentials whose label matches one of the specified pattern(s):
.. code-block:: console
$ pbl list bank
Add the ``-i`` option to also print the credential’s unique identifier.
This identifier will be needed to edit or delete the credential.
.. code-block:: console
$ pbl list -i
To print the actual contents of a credential, use the ``show`` command.
The command will either print all available credentials (if called
without any argument), all the credentials matching the specified
pattern(s), or the one credential with the unique identifier specified
with the ``-i`` option.
You will be asked for the vault’s passphrase to decrypt the encrypted
.. code-block:: console
$ pbl show bank
Passphrase for vault MyVault on
+---- bank.example (31) -----
| URL: https://bank.example/
| Email:
| Password: 123456
Adding, editing, and deleting credentials
Use the ``new`` command to create a new credential and add it to the
vault. The command will fire your favorite editor (as specified in the
``$EDITOR`` environment variable) in which you will be able to set the
contents of the credentials to add. Once you are done, save your
modifications and quit the editor.
To edit an existing credential, use the ``edit`` command with a single
argument representing the unique identifier of the credential to edit
(as displayed by ``list -i``). Again, your editor will be started and
loaded with a textual representation of the credential for you to edit.
The modified credential is sent to the server when you quit the editor
after saving your modifications.
When you are in the editor, if you wish to cancel adding a new
credential or modifying an existing credential, simply quit the editor
without saving anything.
To delete a credential, use the ``del`` command with a single argument
representing the unique identifier of the credential to delete.
.. warning::
As of now (with version |version|), no confirmation is asked before
deleting the credential.

+ 7
- 0 View File

@ -35,5 +35,12 @@ setup(
'console_scripts': [
'pbl = incenp.pebble.__main__:main'
command_options = {
'build_sphinx': {
'project': ('', 'Pebble'),
'version': ('', __version__),
'release': ('', __version__)