From 95574831e700bd481d5dbe918fde305585411535 Mon Sep 17 00:00:00 2001

From: Randy Barlow <randy@electronsweatshop.com>

Date: Thu, 11 Aug 2016 16:16:01 -0400

Subject: [PATCH 2/2] Add a basic man page for the bodhi 2 cli.

---

 docs/conf.py       |   6 +-

 docs/index.rst     |   1 +

 docs/man_bodhi.rst | 250 +++++++++++++++++++++++++++++++++++++++++++++++++++++

 4 files changed, 255 insertions(+), 3 deletions(-)

 create mode 100644 docs/man_bodhi.rst

diff --git a/docs/conf.py b/docs/conf.py

index 12c6746..9f2b49b 100644

--- a/docs/conf.py

+++ b/docs/conf.py

@@ -11,6 +11,7 @@

 # All configuration values have a default; values that are commented out

 # serve to show the default.

+import datetime

 import sys, os

 # If extensions (or modules to document with autodoc) are in another directory,

@@ -43,7 +44,7 @@ master_doc = 'index'

 # General information about the project.

 project = u'bodhi'

-copyright = u'2007-2014, Red Hat, Inc.'

+copyright = u'2007-{}, Red Hat, Inc.'.format(datetime.datetime.utcnow().year)

 # The version info for the project you're documenting, acts as replacement for

 # |version| and |release|, also used in various other places throughout the

@@ -215,8 +216,7 @@ latex_documents = [

 # One entry per manual page. List of tuples

 # (source start file, name, description, authors, manual section).

 man_pages = [

-    ('index', 'bodhi', u'bodhi Documentation',

-     [u'Luke Macken'], 1)

+    ('man_bodhi', 'bodhi', u'manage Fedora updates', ['Randy Barlow', 'Luke Macken'], 1)

 ]

 # If true, show URL addresses after external links.

diff --git a/docs/index.rst b/docs/index.rst

index b233638..fb2a3d9 100644

--- a/docs/index.rst

+++ b/docs/index.rst

@@ -11,6 +11,7 @@ Contents:

 .. toctree::

    :maxdepth: 2

+   man_bodhi

    services

diff --git a/docs/man_bodhi.rst b/docs/man_bodhi.rst

new file mode 100644

index 0000000..7cc368b

--- /dev/null

+++ b/docs/man_bodhi.rst

@@ -0,0 +1,250 @@

+==================

+bodhi CLI man page

+==================

+

+Synopsis

+========

+

+``bodhi`` COMMAND SUBCOMMAND [OPTIONS] [ARGS]...

+

+

+Description

+===========

+

+``bodhi`` is the command line interface to bodhi, Fedora's update release management system. It can

+be used to create or modify updates and overrides.

+

+

+Options

+=======

+

+Most of the commands will accept these three options:

+

+``--help``

+

+    Show help text and exit.

+

+``--password <text>``

+

+    A password to authenticate as the user given by ``--user``.

+

+``--staging``

+

+    Use the staging bodhi instance instead of the production instance.

+

+``--user <username>``

+

+    Many commands accept this flag to specify which user's updates should be operated upon.

+

+

+Commands

+========

+

+There are two commands, ``overrides`` and ``updates``. They are described in more detail in their

+own sections below.

+

+``bodhi overrides <subcommand> [options] [args]``

+

+    Provides commands to aid in management of build overrides. Supports subcommands ``query`` and

+    ``save``, described below.

+

+``bodhi updates <subcommand> [options] [args]``

+

+    Provides an interface to manage updates. Supports subcommands ``comment``, ``download``,

+    ``new``, ``query``, and ``request``, described below.

+

+

+Overrides

+=========

+

+The ``overrides`` command allows users to manage build overrides.

+

+``bodhi overrides query [options]``

+

+    The ``query`` subcommand provides an interface for users to query the bodhi server for existing

+    overrides.

+

+``bodhi overrides save [options] <nvr>``

+

+    Save the build root given by ``<nvr>`` as a buildroot override. The ``save`` subcommand supports

+    the following options:

+

+    ``--duration <days>``

+

+        The number of days the override should exist, given as an integer.

+

+    ``--notes <text>``

+

+        Notes on why this override is in place.

+

+

+Updates

+=======

+

+The ``updates`` command allows users to interact with bodhi updates.

+

+``bodhi updates comment [options] <update> <text>``

+

+    Leave the given text as a comment on a bodhi update. The ``comment`` subcommand

+    supports the following options:

+

+    ``--karma [+1 | 0 | -1]``

+

+        The karma value you wish to contribute to the update.

+

+``bodhi updates download [options]``

+

+    Download update(s) given by CVE(s), ID(s), or NVR(s). One of ``--cves``, ``--updateid``, or

+    ``builds`` is required. The download subcommand supports the following options:

+

+    ``--cves <cves>``

+

+        A comma-separated list of CVEs that identify updates you would like to download.

+

+    ``--updateid <ids>``

+

+        A comman-separated list of update IDs you would like to download.

+

+    ``--builds 

+

+        A comma-separated list of NVRs that identify updates you would like to download.

+

+``bodhi updates new [options] <builds>``

+

+    Create a new bodhi update containing the builds, given as a space separated list of NVRs. The

+    ``new`` subcommand supports the following options:

+

+    ``--type [security | bugfix | enhancement | newpackage]``

+

+        The type of the new update.

+

+    ``--notes <text>``

+

+        The description of the update.

+

+    ``--notes-file <path>``

+

+        A path to a file containing a description of the update.

+

+    ``--bugs <bugs>``

+

+        A comma separated list of bugs to associate with this update.

+

+    ``--close-bugs``

+

+        If given, this flag will cause bodhi to close the referenced bugs automatically when the

+        update reaches stable.

+

+    ``--request [testing | stable | upush]``

+

+        The repository requested for this update.

+

+    ``--autokarma``

+

+        Enable autokarma for this update.

+

+    ``--stable-karma <integer>``

+

+        Configure the stable karma threshold for the given value.

+

+    ``--unstable-karma <integer>``

+

+        Configure the unstable karma threshold for the given value.

+

+    ``--suggest [logout | reboot]``

+

+        Suggest that the user logout or reboot upon applying the update.

+

+    ``--file <path>``

+

+        A path to a file containing all the update details.

+

+``bodhi updates query [options]``

+

+    Query the bodhi server for updates. The ``query`` subcommand supports the following options:

+

+    ``--updateid <id>``

+

+        Query for the update given by id.

+

+    ``--approved-since <timestamp>``

+

+        Query for updates approved after the given timestamp.

+

+    ``--modified-since <timestamp>``

+

+        Query for updates modified after the given timestamp.

+

+    ``--builds <builds>``

+

+        Query for updates containing the given builds, given as a comma-separated list.

+

+    ``--bugs <bugs>``

+

+        Query for updates related to the given bugs, given as a comma-separated list.

+

+    ``--critpath``

+

+        Query for updates submitted for the critical path.

+

+    ``--cves <cves>``

+

+        Query for updates related to the given CVEs, given as a comma-separated list.

+

+    ``--packages <packages>``

+

+        Query for updates related to the given packages, given as a comma-separated list.

+

+    ``--pushed``

+

+        Query for updates that have been pushed.

+

+    ``--pushed-since <timestamp>``

+

+        Query for updates that have been pushed after the given timestamp.

+

+    ``--releases <releases>``

+

+        Query for updates related to a list of releases, given as a comma-separated list.

+

+    ``--locked``

+

+        Query for updates that are currently locked.

+

+    ``--request [testing | stable | unpush]``

+

+        Query for updates marked with the given request type.

+

+    ``--submitted-since <timestamp>``

+

+        Query for updates that were submitted since the given timestamp.

+

+    ``--status [pending | testing | stable | obsolete | unpushed | processing]``

+

+        Filter by status.

+

+    ``--suggest [logout | reboot]``

+

+        Filter for updates that suggest logout or reboot to the user.

+

+    ``--type [newpackage | security | bugfix | enhancement]``

+

+        Filter by update type.

+

+    ``--user 

+

+        Filter for updates by the given username.

+

+``bodhi updates request [options] <update> <state>``

+

+    Request that the given update be changed to the given state. ``update`` should be given by

+    update id, and ``state`` should be one of testing, stable, unpush, obsolete, or revoke.

+

+

+Bugs

+====

+

+If you find bugs in bodhi (or in the mage page), please feel free to file a bug report or a pull

+request::

+

+    https://github.com/fedora-infra/bodhi

-- 

2.7.4