The poll directive allows students to vote or rate topics on a scale.


The general format of the poll directive is:

.. poll:: unique_id
   :optional: parameter value

   + --- Content area ---
   | A question or prompt
   + --------------------

Required Arguments

unique id

A unique identifier after a space and the :: in the poll directive. Valid identifiers must not contain spaces. You should also avoid the characters `` ` , ``,, :, and *.

Optional Arguments

content area

The poll directive should contain at least one line of content to serve as a prompt for the poll.


Boolean. If present, renders a comment box underneath the poll. Default is no comment box.

option_N (through 10)

String. Define up to 10 a manually specified entries. The provided parameter defines the text displayed for this option.

  • The value after the underscore must be in the range 1 through 10.

  • Plain text only.

  • The order defined also specifies the rendering order.

  • This option is ignored if :scale: is present.


Integer. Implements the “On a scale of 1 to N” type method of poll. The provided parameter defines the maximum scale value.

Languages supported

Not applicable.

Sphinx configuration options

No directive specific configuration options exist.



Known limitations

Polls require a backing database to be useful.

Polls are always oriented vertically. There is no way to change the orientation of the option buttons.

The question text must be plain text. No embedded Sphinx markup or HTML formatting is allowed.

There is no upper bound on the :scale: value. A large value could cause long page loads and take large amounts of space.

There is no check when using both both :scale: and :option_N:. If the scale option is used, then the :option_N: options are ignored.


A simple example using the :scale: option with comments enabled.

.. poll:: poll-ex1
   :scale: 5

   On a scale from 1 to 5, 
   how important do **you** think it is to have a polling directive in the <em>Runestone</em>?
    On a scale from 1 to 5, how important do **you** think it is to have a polling directive in the Runestone?
  • 1
  • 2
  • 3
  • 4
  • 5

An example using :option_N: options to manually configure choices.

.. poll:: poll-ex2
   :option_1: Red
   :option_2: Orange
   :option_3: Yellow
   :option_4: Green
   :option_5: Blue
   :option_6: Indigo
   :option_7: Violet

   What is your favorite color in the rainbow?
    What is your favorite color in the rainbow?
  • 1. Red
  • 2. Orange
  • 3. Yellow
  • 4. Green
  • 5. Blue
  • 6. Indigo
  • 7. Violet

Note that a ‘null poll’ won’t throw any warnings, but does not render anything useful in your book.

.. poll:: poll-ex3

This might happen if you make a mistake indenting your poll markup.

You have attempted of activities on this page