From c46465c3255a9f5e59a05b8701e06054df39f32f Mon Sep 17 00:00:00 2001
From: Ivan Bogomazov <ibogomazov@mirantis.com>
Date: Thu, 21 Jul 2016 16:58:42 +0300
Subject: [PATCH] Add documentation for packetary

Closes-bug: #1604989
Closes-bug: #1604996

Change-Id: Ib214006c4852af9b08702368d55f157f7bba089a
---
 doc/source/installation.rst |  41 ++++++++++--
 doc/source/usage.rst        | 125 +++++++++++++++++++++++++++++++++++-
 2 files changed, 159 insertions(+), 7 deletions(-)

diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 532b3f1..509e7ea 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -2,11 +2,42 @@
 Installation
 ============
 
-At the command line::
+Install system requirements - DEB based OS::
 
-    $ pip install packetary
+    ~ $ sudo aptitude install yum \
+        yum-utils \
+        createrepo \
+        mock \
+        sbuild \
+        git \
+        libxml2-dev \
+        libxslt1-dev \
+        python-dev \
+        python-virtualenv \
+        zlib1g-dev
 
-Or, if you have virtualenvwrapper installed::
+Install system requirements - RPM based OS::
 
-    $ mkvirtualenv packetary
-    $ pip install packetary
+    ~ $ sudo aptitude install yum \
+        yum-utils \
+        createrepo \
+        mock \
+        sbuild \
+        git \
+        libxml2-devel \
+        libxslt1-devel \
+        python-devel \
+        python-virtualenv \
+        zlib-devel
+
+Install from sources::
+
+    ~ $ git clone https://git.openstack.org/openstack/packetary
+    ~ $ cd packetary/
+    ~/packetary$ virtualenv .venv
+    ~/packetary$ source .venv/bin/activate
+    ~/packetary$ pip install -r requirements.txt
+    ~/packetary$ python setup.py install
+
+Install from package::
+    ~ $ pip install packetary
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index c061172..5cbba55 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,6 +2,127 @@
 Usage
 ========
 
-To use packetary in a project::
+Build packages with packetary
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    import packetary
+Build packages::
+
+    ~/packetary$ packetary build --type rpm \
+                 --input-data packages.yaml \
+                 --output-dir /tmp/rpm/packages
+
+Format of repos.yaml and packages.yaml provided below.
+
+packages.yaml::
+
+    - source: /home/arno/projects/mirantis/mock-sandbox/zeromq
+      spec: /home/arno/projects/mirantis/mock-sandbox/zeromq/zeromq.spec
+      release: centos-5-x86_64
+
+    - source: /home/arno/projects/mirantis/mock-sandbox/zeromq
+      spec: /home/arno/projects/mirantis/mock-sandbox/zeromq/zeromq.spec
+      release: centos-7-x86_64
+
+
+Clone custom repositories
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Cloning rpm repos::
+
+    packetary clone -t rpm \
+                    -r centos_mirror.yaml \
+                    -R centos_packages.yaml \
+                    -d /tmp/mirror
+
+Clone deb repos::
+
+    packetary clone -t deb \
+                    -r ubuntu_mirrors.yaml \
+                    -R ubuntu_packages.yaml \
+                    -d /tmp/mirror
+
+where:
+
+-t - rpm or deb. In our case we work with rpm repos
+
+-r - mirror(s) list to work with
+
+-R - additional filter that should be applied to repo,
+     eg.: clone exact packages, exclude some packages by name
+     (for example, debuginfo)
+
+YAML examples below
+
+centos_mirror.yaml::
+
+     - name: "mos-repos"
+       uri: "http://mirror.seed-cz1.fuel-infra.org/mos-repos/centos/mos-master-centos7/os/x86_64/"
+       priority: 1
+       path: "/tmp/mirror/mos-centos"
+
+     - name: "upstream-os"
+       uri: http://mirror.centos.org/centos/7/os/x86_64
+       priority: 90
+       path: "/tmp/mirror/centos"
+
+     - name: "upstream-updates"
+       uri: "http://mirror.centos.org/centos/7/updates/x86_64"
+       priority: 10
+       path: "/tmp/mirror/centos"
+
+     - name: "upstream-extras"
+       uri: "http://mirror.centos.org/centos/7/extras/x86_64"
+       priority: 90
+       path: "/tmp/mirror/centos"
+
+centos_packages.yaml::
+
+    repositories:
+        - name: mos-repos
+          excludes:
+              - name: "/^.*debuginfo.*/"
+
+    packages:
+        - name: Cython
+        - name: GeoIP
+        - name: MySQL-python
+        - name: NetworkManager
+        - name: NetworkManager-team
+        - name: NetworkManager-tui
+        - name: PyPAM
+        # fuel packages
+        - name: fencing-agent
+        - name: fuel
+        - name: fuel-agent
+        - name: fuel-bootstrap-cli
+        - name: fuel-ha-utils
+        - name: fuel-library
+        - name: fuelmenu
+        - name: fuel-migrate
+
+ubuntu_packages.yaml::
+
+    mandatory: exact
+
+    # we don't need debug packages
+    repositories:
+        - name: "ubuntu"
+          excludes:
+              - group: "debug"
+
+    packages:
+        - name: aodh-api
+        - name: aodh-common
+        - name: aodh-doc
+        - name: aodh-evaluator
+        - name: aodh-expirer
+        - name: aodh-listener
+
+ubuntu_mirrors.yaml::
+
+    - name: "mos9.0-ubuntu"
+      uri: "http://mirror.seed-cz1.fuel-infra.org/mos-repos/ubuntu/9.0/"
+      suite: "mos9.0"
+      section: ["main", "restricted"]
+      priority: 1000
+       path: "/tmp/mirrors/ubuntu"