[Buildbot-commits] [Buildbot] #2440: Write custom Sphinx support for config class definitions

[Buildbot]

#2440: Write custom Sphinx support for config class definitions
------------------------+--------------------------
Reporter:  dustin       |      Owner:
    Type:  enhancement  |     Status:  new
Priority:  major        |  Milestone:  0.8.+
 Version:  0.8.7p1      |   Keywords:  docs, sprint
------------------------+--------------------------
 Buildbot has a number of change sources, schedulers, steps, and status
 listeners -- all of which are added to the configuration by calling their
 constructors.  These are currently identified for indexing by constructs
 like
 {{{
 .. bb:sched:: NightlyTriggerable
 }}}

 and the parameters are listed simply as
 {{{
 ``builderNames``
     Blah blah blah
 }}}

 This has a few problems:
  * the output is ugly
  * it's not always clear what the parameters are
  * there's no good way to include "common parameters" for each class,
 without copy/pasting them all over the .rst files

 With a little custom programming in the 'bb' Sphinx domain, this could
 probably be fixed.  Something like

 {{{
 .. bb:sched:: NightlyTriggerable

     :includeparams common:
     :includeparams timed:
     :param integer someOtherParam: some other parameter for the scheduler

     This scheduler is a mix of the Nightly and Triggerable schedulers.
     ....
 }}}

-- 
Ticket URL: <http://trac.buildbot.net/ticket/2440>
Buildbot <http://buildbot.net/>
Buildbot: build/test automation