[docs] several doc updates

4 files changed, 57 insertions, 19 deletions

diff --git a/docs/hacking/index.rst b/docs/hacking/index.rst
index ada3a78a..d2ebd68b 100644
--- a/docs/hacking/index.rst
+++ b/docs/hacking/index.rst
@@ -27,17 +27,19 @@ If you are developing against a non-published branch of ``leap.common`` or
 This expects ``leap_common`` and ``soledad`` repos to be checked out in the
 parent folder.
 
+.. _devenv:
+
 Setting up the development environment
 --------------------------------------
 
-Dependencies::
+Install the system-wide dependencies. For debian-based systems::
 
   sudo apt install build-essential python-dev python-virtualenv \
   libsqlcipher-dev libssl-dev libffi-dev \
   python-pyqt5 python-pyqt5.webkit
 
 
-Clone the repo::
+Clone the repo. The master branch has the latest code::
 
   git clone https://0xacab.org/leap/bitmask-dev
   cd bitmask-dev
@@ -54,6 +56,12 @@ Now you should be able to install all the bitmask dependencies::
 
   make dev-latest-all
 
+You can also install some dependencies that are going to be useful during
+development::
+
+  pip install -r pkg/requirements-dev.pip
+
+
 .. _`pew`: https://pypi.python.org/pypi/pew
 
 
@@ -144,7 +152,7 @@ Making a new release
 
 A checklist for the release process can be found :ref:`here <release>`
 
-As part of the release we also tag upload snapshots of the `leap.bitmask_js`
+As part of the release we also tag upload snapshots of the ``leap.bitmask_js``
 package, in order to allow installation of the javascript application without
 needing to compile the javascript and html assets. This is done with::
 
diff --git a/docs/installation/index.rst b/docs/installation/index.rst
index ce119e69..e278a5e1 100644
--- a/docs/installation/index.rst
+++ b/docs/installation/index.rst
@@ -5,8 +5,8 @@
 .. _install:
 
 
-Installation
-==================
+Installation and packaging 
+==========================
 
 Users: go to the Bitmask Install guide https://bitmask.net/en/install
 
@@ -18,13 +18,43 @@ Translators: improved/new translations welcome!
 
 Running latest code
 -------------------
-blah blah
+
+Refer to the :ref:`setting up the development environment <devenv>` section to
+learn how to run Bitmask from the latest code in the master branch.
 
 Building new bundles
 --------------------
-blah blah...
-nightly builds...
-building bleeding edge bundles...
+
+The standalone bundles are built with PyInstaller.
+
+If you are inside a development virtualenv, you should be able to install it
+together with some extra development dependencies with::
+
+  pip install -r pkg/requirements-dev.pip
+
+And then just do::
+
+  make bundle
+
+To build a new bundle.
+
+There's also a script that automates re-creating the virtualenv from which the
+packaging takes place:: 
+  
+  pkg/build_bundle_with_venv.sh
+
+To ensure a repeatable system-wide environment, you can build those bundles from
+within a docker container. First you need to create the container::
+
+  make docker_container
+
+and then you can launch the above script inside that container::
+
+  make bundle_in_docker
+
+A new bundle is created by the CI for every commit using this procedure
+involving docker, you can read more about the bundles in the :ref:`qa section
+<qa>`.
 
 Debian packages
 ---------------
@@ -35,7 +65,6 @@ https://bitmask.net/en/install/linux#ubuntu-packages
 debian:
 https://bitmask.net/en/install/linux#debian-packages
 
-Experimental repo ...
 
 Building latest packages (TBD).
 
diff --git a/docs/mail/index.rst b/docs/mail/index.rst
index bd5cfa1c..d906c511 100644
--- a/docs/mail/index.rst
+++ b/docs/mail/index.rst
@@ -44,20 +44,18 @@ All the underlying data storage and sync is handled by a library called
 documents are stored locally as local ``sqlcipher`` tables, and syncs against
 the soledad sync service in the provider.
 
-OpenPGP key generation and keyring management are handled by another leap
-python library: `keymanager`_.
+OpenPGP key generation, discovery, validation, and keyring management are
+handled by the ``leap.bitmask.keymanager`` module.
 
-See :ref:`the life cycle of a leap email <mail_journey>` for an overview of the life cycle
-of an email through ``LEAP`` providers.
 
 .. _`Soledad`: https://leap.se/en/docs/design/soledad
 .. _`u1db`: https://en.wikipedia.org/wiki/U1DB
-.. _`keymanager`: https://github.com/leapcode/keymanager/
 
 The life cycle of a LEAP Email
 ------------------------------
 
-For a better picture, you are invited to read about :ref:`the whole journey of a mail in the LEAP system <journey>`.
+See :ref:`the life cycle of a leap email <mail_journey>` for an overview of the life cycle
+of an email through ``LEAP`` providers.
 
 
 Data model
@@ -65,9 +63,11 @@ Data model
 
 .. TODO clear document types documentation.
 
-The data model at the present moment consists of several *document types* that split email into different documents that are stored in ``Soledad``. The idea behind this is to
-keep clear the separation between *mutable* and *inmutable* parts, and still being able to
-reconstruct arbitrarily nested email structures easily.
+The data model at the present moment consists of several *document types* that
+split email into different documents that are stored in ``Soledad``. The idea
+behind this is to keep clear the separation between *mutable* and *inmutable*
+parts, and still being able to reconstruct arbitrarily nested email structures
+easily.
 
 Authentication
 ---------------------
diff --git a/pkg/requirements-dev.pip b/pkg/requirements-dev.pip
index 59fbd696..e63d9646 100644
--- a/pkg/requirements-dev.pip
+++ b/pkg/requirements-dev.pip
@@ -1,5 +1,6 @@
 ipython
 ptpython
 ipdb
+PyInstaller
 sphinx
 sphinx_rtd_theme