Sphinx for writing "parallel text"

Question

Problem: I am trying to write "parallel text" using reStructuredText . By “parallel text” I mean something like annotated works of fiction, where the text is in two columns. The left column contains the main text, and the right column contains the comment. I will use sphinx to create HTML and Latex documentation.

I have the following requirements:

• As mentioned above, I should be able to type in two columns, one for the main text and one for the annotations.
• Annotations can be a “sentence level” and will not always be a “paragraph level”. Ie, I want to be able to comment on various sentences in a paragraph or a whole paragraph.
• It will be great to have a mode in which all annotations are disabled, so the output HTML and latex contain only the main text. In this case, I would like to be able to use all the "real estate" for the environment, and not just for the column.
• It will be very nice to have the Annotation List feature, if possible.

I am new to reStructuredText and Sphinx, but have a lot of experience with Python. I am looking for some ideas on how to do what I want to do. I read about reStructuredText, as well as writing Sphinx extensions, so writing an extension for Sphinx is out of the question.

Has anyone done something like this before?

Thanks!

Answer 1

Do they seem very similar to footnotes? I would suggest taking a look at http://ignorethecode.net/blog/2010/04/20/footnotes/

If they fit your purpose, integrating them should not be too complicated. Sphinx displays footnotes with a special class. Replacement

$ ("A [rel = 'Footnote']")

in code, with the jquery css selector of your choice, you should give you what you want.