From 68b8264c3e15612cdb62f7696e859cc866c88e48 Mon Sep 17 00:00:00 2001 From: Lukas Holecek Date: May 09 2018 15:16:05 +0000 Subject: [PATCH 1/2] Add user documentation Fixes #149 --- diff --git a/docs/client-conf.rst b/docs/client-conf.rst new file mode 100644 index 0000000..5e5a09b --- /dev/null +++ b/docs/client-conf.rst @@ -0,0 +1,44 @@ +.. _client-conf: + +========================== +waiverdb-cli Configuration +========================== + +Description +=========== + +The file :file:`/etc/waiverdb/client.conf` contains configuration for +:ref:`waiverdb-cli(1) `, a tool for reading and modifying +WaiverDB. + +Options +======= + +``[waiverdb]`` - Configuration section for ``waiverdb-cli`` + +``api_url`` - Base URL for WaiverDB API + +``auth_method`` - Authentication method - ``OIDC`` (OpenID Connect) or ``Kerberos`` + +Following options are valid only if ``auth_method`` is set to ``OIDC``. + +``oidc_id_provider`` - URL of the identity provider for OIDC to get tokens from + +``oidc_client_id`` - OIDC client ID to request credentials + +``oidc_client_secret`` - OIDC client "secret" to request credentials + +``oidc_scopes`` - A list of scopes required for OIDC client + +Files +===== + +:file:`/usr/share/doc/waiverdb/client.conf.example` + + Template for configuration file. + +Example +======= + +.. include:: ../conf/client.conf.example + :literal: diff --git a/docs/conf.py b/docs/conf.py index a645ee5..06d05b8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -149,9 +149,11 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('waiverdb-cli', 'waiverdb-cli', u'waiverdb-cli Documentation', + ('waiverdb-cli', 'waiverdb-cli', u'WaiverDB Client', [author], 1), - ('api', 'waiverdb', u'WaiverDB Documentation', + ('client-conf', 'client.conf', u'waiverdb-cli configuration file', + [author], 5), + ('api', 'waiverdb', u'WaiverDB REST API', [author], 7) ] diff --git a/docs/index.rst b/docs/index.rst index 4ec38bc..768a797 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,9 +8,11 @@ test results. :maxdepth: 2 :caption: Contents: - developer-guide + user-guide api waiverdb-cli + client-conf + developer-guide release-notes diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 0000000..d67ea21 --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,56 @@ +========== +User Guide +========== + +WaiverDB is service allowing to waive test results from `ResultsDB`_. + +You can use :ref:`rest-api` to modify and query waived states. To simplify +making requests, use ``waiverdb-cli``. + +waiverdb-cli +============ + +``waiverdb-cli`` is command-line tool for modifying and querying waived +states stored in WaiverDB server. + +Use ``--help`` to see common usage. For more details refer to +:ref:`waiverdb-cli(1) ` manual page (``man 1 waiverdb-cli``). + +Examples +-------- + +Waive test results with IDs 47 and 48 and specific product version:: + + waiverdb-cli -r 47 -r 48 -p "fedora-28" -c "This is fine" + +Waive test results with specific subject and product version:: + + waiverdb-cli -t dist.rpmdeplint \ + -s '{"item": "qclib-1.3.1-3.fc28", "type": "koji_build"}' \ + -p "fedora-28" -c "This is expected for non-x86 packages" + +Installation +------------ + +Either install system package, e.g. on Fedora:: + + $ sudo dnf install waiverdb-cli + +or install ``waiverdb`` PyPI package:: + + $ pip install --user waiverdb + +.. _ResultsDB: https://pagure.io/taskotron/resultsdb + +Configuration +------------- + +The tool reads a configuration file to know which server and authentication +method to use. + +Default configuration is taken from :file:`/etc/waiverdb/client.conf`. You can +use ``--config-file`` flag to specify different one. + +For more details about the configuration file refer to +:ref:`waiverdb-client.conf(5) ` manual page (``man 5 +waiverdb-client.conf``). diff --git a/docs/waiverdb-cli.rst b/docs/waiverdb-cli.rst index 9631563..3d539ff 100644 --- a/docs/waiverdb-cli.rst +++ b/docs/waiverdb-cli.rst @@ -1,3 +1,5 @@ +.. _waiverdb-cli: + ============ waiverdb-cli ============ diff --git a/waiverdb.spec b/waiverdb.spec index 0668ddd..0f41683 100644 --- a/waiverdb.spec +++ b/waiverdb.spec @@ -139,6 +139,10 @@ install -D -m0644 \ %{buildroot}%{_mandir}/man1/waiverdb-cli.1 install -D -m0644 \ + docs/_build/man/client.conf.5 \ + %{buildroot}%{_mandir}/man5/waiverdb-client.conf.5 + +install -D -m0644 \ docs/_build/man/waiverdb.7 \ %{buildroot}%{_mandir}/man7/waiverdb.7 %endif @@ -179,6 +183,7 @@ install -D -m0644 \ %if 0%{?fedora} || 0%{?rhel} > 7 %{_mandir}/man1/waiverdb-cli.1* +%{_mandir}/man5/waiverdb-client.conf.5* %{_mandir}/man7/waiverdb.7* %endif From 3a89f96a5bfe156c762c235b7c2af530023cc862 Mon Sep 17 00:00:00 2001 From: Lukas Holecek Date: May 09 2018 15:16:05 +0000 Subject: [PATCH 2/2] Add git repo set up instructions to documentation --- diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index 3add5f7..2bd1b8b 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -5,6 +5,17 @@ Development Guide Quick development setup ======================= +Clone `upstream git repository `__:: + + $ git clone https://pagure.io/waiverdb.git + $ cd waiverdb + +If you plan to fix issues or implement new features, create fork. Then update +"upstream" and "origin" remotes:: + + $ git remote rename origin upstream + $ git remote add origin ssh://git@pagure.io/forks/$USER/waiverdb.git + Install packages required by pip to compile some python packages:: $ sudo dnf install swig openssl-devel cpp gcc