PR#423: Fix docs to reflect latest packaging changes - taskotron/libtaskotron

taskotron / libtaskotron

#423 Fix docs to reflect latest packaging changes

Merged 5 years ago by kparal. Opened 5 years ago by kparal.

feature/docs into develop

docs: adjust guides for packaging python2/3 split

Kamil Páral • 5 years ago

264619f

docs: fix building directives

Kamil Páral • 5 years ago

1bcbb96

docs/generate_directive_docs.py

file modified

+5 -2

		`@@ -45,6 +45,8 @@`
		`os.pardir,`
		`'libtaskotron'))`

		`+ CATEGORY_NAME='directives'`
		`+`
		`_ITALIC = re.compile(r"I\(([^)]+)\)")`
		`_BOLD = re.compile(r"B\(([^)]+)\)")`
		`_MODULE = re.compile(r"M\(([^)]+)\)")`
		`@@ -470,6 +472,7 @@`
		`categories = list_modules(options.module_dir)`
		`category_names = categories.keys()`
		`category_names.sort()`
		`+ assert CATEGORY_NAME in category_names`

		`# Create the 'directives' directory if it doesn't exist`
		`if not os.path.exists(options.output_dir):`
		`@@ -486,8 +489,8 @@`
		`category_list_file.write(".. toctree::\n")`
		`category_list_file.write(" :maxdepth: 1\n\n")`

		`- category_list_file.write(" list_of_%s_modules\n" % category_names[1])`
		`- process_category(category_names[1],`
		`+ category_list_file.write(" list_of_%s_modules\n" % CATEGORY_NAME)`
		`+ process_category(CATEGORY_NAME,`
		`categories,`
		`options,`
		`env,`

docs/source/devguide.rst

file modified

+8 -18

		`@@ -42,7 +42,6 @@`
		`createrepo_c \`
		`gcc \`
		`git \`
		`- libtaskotron-config \`
		`python3-doit \`
		`python2-hawkey \`
		`python3-hawkey \`
		`@@ -105,16 +104,17 @@`
		`Configuration`
		`=============`

		- The ``libtaskotron-config`` package installs config files with default values
		- into ``/etc/taskotron``. If you need to change those default values, you can
		- either change the files in ``/etc/taskotron`` or you can create config files
		`- inside your checkout with::`
		+ Libtaskotron searches ``/etc/taskotron`` and a ``conf/`` dir in your local
		`+ checkout for configuration files. There's currently one config file that is`
		`+ mandatory to be present, so if you don't have libtaskotron RPMs installed, make`
		`+ sure it is present (and keep it up-to-date), like this::`

		`- cp conf/taskotron.yaml.example conf/taskotron.yaml`
		`cp conf/yumrepoinfo.conf.example conf/yumrepoinfo.conf`

		- The configuration files in ``conf/`` take precedence over anything in ``/etc``,
		`- so make sure that you're editing the correct file if you create local copies.`
		`+ If you need to override the default values of other config files, you can copy`
		+ over the ``*.example`` files in the ``conf/`` dir in a similar fashion and edit
		+ them. The configuration files in ``conf/`` take precedence over anything in
		+ ``/etc``.

		`In the development environment, it's also useful to have taskotron-generated`
		`files automatically cleaned up, so that they don't occupy disk space in vain.`
		`@@ -152,16 +152,6 @@`
		`sufficiently covered by the tests.`


		`- .. FIXME`
		`- Continuous integration`
		`- ^^^^^^^^^^^^^^^^^^^^^^`
		`-`
		`- Ideally, one should run unit/functional tests before sending code for review.`
		`- However, it might happen that code that breaks tests gets pushed, for that we`
		`- have a basic support for running tests after each commit at`
		`- https://qa.fedoraproject.org/buildmaster/waterfall.`
		`-`
		`-`
		`.. _submitting-code:`

		`Submitting code`

docs/source/quickstart.rst

file modified

+3 -3

		`@@ -7,9 +7,9 @@`
		`Install`
		`=======`

		- Install ``libtaskotron``::
		+ Install ``taskotron-runner``::

		`- sudo dnf install libtaskotron`
		`+ sudo dnf install taskotron-runner`

		See :ref:`libtaskotron-modules` for more information on installing individual
		`modules.`
		`@@ -72,7 +72,7 @@`

		`.. code-block:: none`

		`- runtask --item htop-2.0.2-4.fc27 --type koji_build task-rpmlint/`
		`+ runtask --item htop-2.2.0-2.fc29 --type koji_build task-rpmlint/`

		`The build will be downloaded to a local tempdir, rpmlint will be run against`
		`that build and the results will be saved in an artifacts directory (which will`

docs/source/runningtasks.rst

file modified

+10 -18

		`@@ -20,27 +20,19 @@`
		`libtaskotron modules`
		`--------------------`

		`- As functionality has been added to libtaskotron, we've started breaking up that`
		`- functionality into modules to increase flexibility and shrink the minimal`
		`- install profile. Each module is packaged separately for easy installation.`
		`+ The libtaskotron library is separated into the following RPM subpackages:`

		- libtaskotron is composed of 3 modules - ``libtaskotron-core``,
		- ``libtaskotron-fedora`` and ``libtaskotron-disposable``.
		`+ python2-libtaskotron`
		+ Python 2 modules that tasks can make use of. See :doc:`library`.

		`+ python3-libtaskotron`
		+ Python 3 modules that tasks can make use of. See :doc:`library`.

		`- libtaskotron-core`
		`- The minimum needed to run tasks with libtaskotron. It consists of the most`
		`- basic bits that most tasks will use, and the runner.`
		`-`
		`- libtaskotron-fedora`
		`- The fedora-specific functionality which is in libtaskotron - things like`
		`- bodhi, koji and rpm-based directives.`
		`-`
		`- libtaskotron-disposable`
		`- The bits needed to enable execution with`
		- :ref:`disposable-clients`. Local-only execution is still possible without
		- this module. Note that ``libtaskotron-disposable`` depends on testcloud_
		`- which will pull in several other non-trivial dependencies.`
		`+ taskotron-runner`
		`+ The runner binary which can be used to execute the task on a local or a`
		`+ remote machine. This also depends on libraries (like testcloud_) required for`
		`+ spawning fresh virtual machines for executing tasks, see`
		+ :ref:`disposable-clients`.


		`.. _running-tasks:`

docs/source/writingtasks.rst

file modified

+2 -2

		`@@ -82,7 +82,7 @@`
		``{{artifacts}}/taskotron/results.yml`` file in :doc:`ResultYAML <resultyaml>`
		`format. You can either generate it by hand, or you can use either a`
		standalone command ``taskotron_result`` or a Python library, both provided by
		- the ``libtaskotron-core`` package.
		+ the ``python3-libtaskotron`` package.

		Usage of ``taskotron_result`` is very simple. Run it like this to save a result
		`to a file::`
		`@@ -107,7 +107,7 @@`
		`from libtaskotron import check`

		`def run_mytask(koji_build, artifacts):`
		`- print "Running mytask on %s" % koji_build`
		`+ print("Running mytask on %s" % koji_build)`
		`result = 'PASSED'`
		`detail = check.CheckDetail(item=koji_build,`
		`report_type=check.ReportType.KOJI_BUILD,`