ReStructuredText

ReStructured Text is a human readable text format that renders out to HTML. It was created as a part of the python docutils project.

http://docutils.sourceforge.net/docs/user/rst/quickref.html	Cheat Sheet
http://docutils.sourceforge.net/rst.html	official documentation

Workflow

A big part of restructuredText's purpose is being able to write to HTML, so you'll likely want to preview it sa you write it.

sudo pip install restview

# runs a simple webserver, re-renders an HTML file every time
# the file is saved, refreshes it in a simple web browser.
restview /path/to/file.rst

# Use a specific CSS stylesheet
restview   --css=/path/to/file.css,/path/to/otherfile.css   /path/to/file.rst

set default browser

## Several Browser settings
xdg-mime default application/xhtml+xml firefox.desktop
xdg-mime default text/html             firefox.desktop
xdg-mime default text/mml              firefox.desktop
xdg-mime default text/xml              firefox.desktop

## Relevant Browser settings
xdg-mime default x-scheme-handler/http firefox.desktop
xdg-mime default x-scheme-handler/https firefox.desktop

Syntax

I'll be really brief here, the official documentation is fantastic.

Headers

Headers are defined by an unindented string, underlined by the same number of characters. Subtitles, are the same. The characters used to specify an underline do not

My Page Title
.............

level 2 title
=============

level 3 title
--------------



level 2 title again
===================

Bold, Italic

* italic text *
** bold  text **

Lists

- list item
- list item 2
  - sublist item

- a single newline indicates a new list


1) enumerated list

2) enumerated list 2

#) variable num

images

.. image:: /path/to/image.jpg

Named Links

A sentence with links to Wikipedia_ and the `Linux kernel archive`_.

.. _Wikipedia: http://www.wikipedia.org/
.. _Linux kernel archive: http://www.kernel.org/

Code Blocks

::

	this is a litteral codeblock without any syntax
	highlighting.

.. code-block:: python

   def something():
      """
      some doctag
      """
      return var

tables

=================  =====
**module  desc**   stuff
=================  =====
lkjasdmodule       delkjadssc
module  desc       test something
=================  =====

comments

.. this is a comment

Exporting to PDF

Unfortunately, this is not a straightforward process, but it is simple enough

## if you have a soft background-color, you'll want to change
## it back to white (in the css, or html file)
sudo pacman -S wkhtmltopdf
sudo pip install rst2html

rst2html --stylesheet=$python/libhtml/CSS/pers_rst.css resume.rst resume.html

wkhtmltopdf --page-size Letter \
            -T 10mm -B 10mm    \
            resume.html resume.pdf

## if you are experiencing issues with pixellated fonts, 
## it is likely that you are either
##    a) not using a true-type font
##    b) your true type font is not being found, and a differnet font is being used in it's place
##
## See solution here:
https://github.com/wkhtmltopdf/wkhtmltopdf/issues/2193

#### /etc/fonts/conf.avail/70-no-bitmaps.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
<!-- Reject bitmap fonts -->
 <selectfont>
  <rejectfont>
   <pattern>
     <patelt name="scalable"><bool>false</bool></patelt>
   </pattern>
  </rejectfont>
 </selectfont>
</fontconfig>

ln -s /etc/fonts/conf.avail/70-no-bitmaps.conf /etc/fonts/conf.d/70-no-bitmaps.conf