Custom Directive with header and internal list reStrcuturedText

Question

Basically what I'm trying to do is copy this style (from a word doc) but using rst.

I was thinking I might need a custom directive which I can can include the header and style the internal checkboxes.

Ideally I would like to be able to do something like:

.. handson::

   The title

   - Check one
   - Check two

The bulltet items inside the handson block would be styled as checkboxs but the rest of the document would just have normal bullet points.

I had a look at the custom directive stuff but I'm not sure if that would be the best way to tackle this. I'm also using rst2pdf if that has any impact on the results.

Answer 1

If you don't want to go down the route of creating a custom directive, you could use a normal admonition block and "fake" the check boxes. Your markup could be standard reStructuredText:

.. admonition:: The title

   - Check one
   - Check two

You can then include some custom CSS markup within your reStructuredText file to target list items in admonitions:

.. raw:: html

   <style>
   .admonition ul { list-style-type: none; } 

   .admonition li:before { content: "\2610"; }
   </style>

Here the CSS targets any list item element which is a child of any element with the class "admonition" and replaces the list item bullet points with simulated check boxes using the Unicode Ballot box character, ☐.

Docutils applies an additional class to generic admonitions which is a concatenation of "admonition" and the admonition title. So in the above example we could be more specific with the element we target with the CSS rule:

.admonition-the-title ul { /* ... */ }

This could be used to target a single admonition within your document.

Credit goes to these two answers to the SO question How to create a checklist in reStructuredText (reST)?

Obviously the above targets HTML output. However, I have not used rst2pdf, so can't comment on how the above needs to be modified to work with this program. Hopefully someone else will provide an answer to this. As far as I know, rst2pdf does support a cascading stylesheet mechanism, so it should be straightforward (for someone who knows rst2pdf style sheet syntax) to add an additional .. raw:: pdf role and to modify the above list styles.