When using reStructuredText in Sphinx, how can I have optional list items using the only directive?

As an example:

foo bar:

- a
- b
.. only:: Internal

   - c
- d

The problem with above is that it creates a separate <p> for both - c and - d when generating html. Anyone know how I can have all of these contained within a single <ul> in generated html? Thanks!

When using reStructuredText in Sphinx, how can I have optional list items using the only directive?

As an example:

foo bar:

- a
- b
.. only:: Internal

   - c
- d

The problem with above is that it creates a separate <p> for both - c and - d when generating html. Anyone know how I can have all of these contained within a single <ul> in generated html? Thanks!

• documentation
• python-sphinx
• restructuredtext

• I'd use two complete lists, one for internal the other for external, and use ifconfig. – Steve Piercy Commented Feb 7 at 6:57

1 Answer 1

You cannot place a directive directly between list items. Any text or rST syntax construct at this place breaks the list in two.

The workaround used by Docutils for the "class" directive and internal hyperlink targets is to apply nested "class" directives and targets to the following document tree element 1.

Example: to apply a class value to list item "c", append the "class" directive to the content of item "b":

foo bar:

- a
- b

  .. class:: internal
- c
- d

• The empty line before the "class" directive is required -- otherwise it would be interpreted as continuation line of the preceding paragraph. Empty lines between list items are optional.

• In Sphinx, use "rstclass" instead of "class".

You may try whether Sphinx uses the same concept for the "only" directive. Alternatively, you can use the strip_elements_with_classes Docutils configuration option to remove the "classified" item.