Tips on Using reST with RapidWeaver
I've got a couple of tips on using reST with RapidWeaver (or really, just using reST).
Table of Contents
General
- Keep the Quick Reference handy. It's completely invaluable.
- If you're using Pygments and
the bundled front end, then the following
will be helpful:
- In styled-text pages, choose "convert spaces to " in the settings. This will fix the fact that formatting is destroyed in styled pages.
- Use your CSS. Replace the <pre> and </pre> tags that wrap the output with your own tags and format them appropriately.
- Remember that Pygments is going to tag the
particular bits of your code so you can colour
them. The following are some of the tags:
- c - comments
- nb - functions, I think.
- k - keywords
- s2 - strings
- o - symbols
- nv - variables
Implementing a <pre> section
We all know that styled text pages are going to destroy any <pre> formatting you do. However, you can get it back quite nicely with reST. Mine look like this:
The trick is in two parts. First, you have to mark up with reST like this:
.. container:: <pick some name here> | This is line one | This is line two which is | broken up | into | multiple lines, actually
The vertical bars are shown in the Quick Reference and, essentially, just keep your formatting the way you have it.
You then have to create some CSS (I do it in the theme's styles.css file) that deals properly with the container object (<pick some name here>). This is what mine looks like:
div.styled-pre
{
border-width: 1px;
border-style: solid;
border-color: #066fd4;
background: #000000;
padding: 10px;
line-height: 1.1em;
color: #c8c8c8;
font-family: courier
}
Email Inclusion
I found that including email was a bit of a question mark as well because using a block quote section like this:
From: You To: That guy Subject: Whatever Hey, here's my email content.
Shows up like this when rendered:
From: You To: That guy Subject: Whatever
Hey, here's my email content.
And that clearly sucks. I liked the block quote feel but I needed the formatting to be correct. This is handled much like the Implementing a <pre> section was:
.. container:: email-inclusion | From: You | To: That guy | Subject: Whatever | | Hey, here's my email content.
And, with the following CSS:
div.email-inclusion
{
font-style: italic;
color: #066fd4;
margin-right: 20px;
margin-left: 20px;
}
it will render like this:
Making Lists Look "Right"
reST is going to make lists a little different depending on what you're going to do. If you define a list like this:
- item 1 - item 2 - item 3
Then the result will create the following HTML:
<ul>
<li>item 1</li>
<li>item 2</li>
<li>item 3</li>
</ul>
However, if you define this list:
- item 1 - item 2 - nested item 2.1 - nested item 2.2 - item 3
Then the result will create the following HTML (leaving out the id and class directives):
<ul>
<li>
<p>item 1</p>
</li>
<li>
<p>item 2</p>
<ul>
<li>
<p>nested item
2.1</p>
</li>
<li>
<p>nested item
2.2</p>
</li>
</ul>
</li>
<li>
<p>item 3</p>
</li>
</ul>
which I think is just really, really odd (note the inclusion of the <p> </p> pairs). The point is that the lists won't be uniform; the second list will have more spacing between the items where the first one won't. I like things to look the same so I've defined the following CSS:
/* Make lists nicely
spaced. Why this doesn't make the
<p></p> case
* have more spacing is
confusing to me... But this does what I
want
* it to do */
ul li, ol li
{
margin-bottom: 1em;
}
/* Don't make the spacing
for table of contents
* and the navcontainer in
the sidebar */
div.contents ul li, #navcontainer ul li
{
margin-bottom: 0px;
}
Making Definitions Look "Right"
I don't like the way that definitions are spaced by default. So the following CSS makes things cleaner:
/* Put a nice space
after definition directives */
dl.docutils dd
{
margin-bottom: 1em;
}