This at least needs to be in a new subsection instead of just tacked on at the end. "Working with CheckDetail Objects" seems like an appropriate title to me.

Also, breaking these examples into subsections or subsubsections with their own titles would break things up a bit more and create better direct links to the examples

I think this is a typo (o instead of on)? "for more information about APIs ..." might be a better wording here, though

If I open the rendered documentation in Firefox, there are automatic hyperlinks like library.html#module-libtaskotron.check. I wonder if that can be re-used instead of manually creating custom anchors?

A few clarifications here and below:
CheckDetail.store() is not used for output from several checks. It's used for output from a single check. If you execute several checks (e.g. rpmlint on several different builds), you should create several CheckDetails so that the results are reported separately.

CD.store() simply appends a string to CD.output, which is a list so that it is easy and convenient to work with it and you don't have to deal with line breaks. It doesn't matter whether you append a single line, or 100 lines - at the end, all of that is going to be concatenated together to a single big string -- the check log. CD.store() is a convenience method if you receive some output gradually and you want to store it and also print it at the same time (upgradepath does this). If you don't want to produce results/show progress in real time, and you want to populate CD just at the end, you can either use the constructor (if your CD doesn't exist yet), or directly assign to CD.output.

I think we should mention that the list together with the priorities is accessible as CD.outcome_priority.

Or you can directly set outcome as CD.outcome.

If we don't want to print progress to stream, let's change False to printout=False, so that it's obvious what it does without looking into documentation. But I think this can be one of the places where it actually makes sense to print it, so even if you run it manually in the terminal, you still see all the results easily. What about something like this?

for rpmfile, outcome in results:
    # e.g. "xchat-1.2-3.fc20.x86_64.rpm: FAILED"
    detail.store('%s: %s' % (os.path.basename(rpmfile), outcome))
    detail.update_outcome(outcome)

For the moment, we should append checkname='mytask' here, I guess.

And we will then get rid of $CHECKNAME here.

I'm not sure it's worth having examples even for not-that-important methods and attributes, and broken() seems to be one of them to me. I'd rather see concise documentation covering the most important and useful use cases, than very detailed documentation about every possible option.

In theory, yes, you can do this, but I don't want to even hint this to people until all of us agree it is a good idea. At the moment I'm very unclear what is the benefit of having smaller reporting units than builds (or build-arches). Currently we suppose we will allow people to define their own item_type, so we can't stop them from reporting results per-rpm or even per-file(!). But imagine what this could do to our database. In the end, we will need to introduce some reporting limits, I think. So I wouldn't include this piece of documentation until we're clearer on this topic. Sorry about that, I know it took some time to write this.