Browse Source

Start writing a proper documentation.

The README is not enough, Pebble needs a proper manual.
master
Damien Goutte-Gattat 2 years ago
parent
commit
d83005b643
5 changed files with 273 additions and 0 deletions
  1. +56
    -0
      docs/conf.py
  2. +26
    -0
      docs/index.rst
  3. +70
    -0
      docs/install.rst
  4. +114
    -0
      docs/quickstart.rst
  5. +7
    -0
      setup.py

+ 56
- 0
docs/conf.py 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 <dgouttegattat@incenp.org>'
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.',
'Miscellaneous'),
]

+ 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: https://github.com/nextcloud/passman
.. _Nextcloud: https://nextcloud.com/
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
3.5+.
.. toctree::
:maxdepth: 2
install
quickstart

+ 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: https://pypi.org/project/incenp.pebble/
.. 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: https://incenp.org/dvlpt/pebble.html
.. _release page: https://git.incenp.org/damien/pebble/releases
.. code-block:: console
$ tar zxf incenp.pebble-0.4.0.tar.gz
$ cd incenp.pebble-0.4.0
$ python setup.py build
$ python setup.py install
You may also clone the repository:
.. code-block:: console
$ git clone https://git.incenp.org/damien/pebble.git
and then proceed as above.
Dependencies
============
Pebble requires the following Python dependencies to work:
* `sjcl <https://github.com/berlincode/sjcl>`_
* `requests <http://python-requests.org/>`_
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 <http://www.gnu.org/licenses/gpl.html>.

+ 114
- 0
docs/quickstart.rst View File

@ -0,0 +1,114 @@
***************
Getting Started
***************
Prerequisites
=============
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
[default]
host: cloud.example.org
user: alice
password: XXXXXX
vault: MyVault
where ``cloud.example.org`` 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
example.com
social.example.org
bank.example
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
bank.example
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
29:example.com
30:social.example.org
31:bank.example
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
fields.
.. code-block:: console
$ pbl show bank
Passphrase for vault MyVault on alice@cloud.example.org:
+---- bank.example (31) -----
| URL: https://bank.example/
| Email: alice@example.org
| 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
setup.py View File

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

Loading…
Cancel
Save