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

[Buildbot trac]

#2440: Write custom Sphinx support for config class definitions
-------------------------+--------------------
Reporter:  dustin        |       Owner:
    Type:  enhancement   |      Status:  new
Priority:  major         |   Milestone:  0.9.+
 Version:  master        |  Resolution:
Keywords:  docs, sprint  |
-------------------------+--------------------
Changes (by sa2ajj):

 * version:  0.8.7p1 => master


Old description:

> 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.
>     ....
> }}}

New description:

 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#comment:2>
Buildbot <http://buildbot.net/>
Buildbot: build/test automation