Merge branch 'experimental-html-manual'

Closes #697

doc/assets/manual.css

@@ -0,0 +1,102 @@
+/*
+Stylesheet for Docutils, based on voidspace.css.
+Based on ``blue_box.css`` by Ian Bicking
+and ``html4css1.css`` revision 1.46.
+*/
+
+@import url(html4css1.css);
+
+body {
+  font-family: 'Lucida Grande', 'Calibri', Helvetica, Arial, sans-serif;
+}
+
+a.target {
+  color: darkblue;
+}
+
+a.toc-backref {
+  text-decoration: none;
+  color: black;
+}
+
+a.toc-backref:hover {
+  background-color: inherit;
+}
+
+a:hover {
+  background-color: #cccccc;
+}
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+  background-color: #cccccc;
+  padding: 3px;
+  width: 80%;
+}
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title  {
+  text-align: center;
+  color: white;
+  font-size: 120%;
+  font-weight: bold;
+  background-color: #999999;
+  display: block;
+  margin: 0;
+}
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: #cc0000;
+  font-family: sans-serif;
+  text-align: center;
+  background-color: #999999;
+  display: block;
+  margin: 0;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: 'Lucida Grande', 'Calibri', Helvetica, Arial, sans-serif;
+  padding: 4px;
+}
+
+h3 a.toc-backref, h4 a.toc-backref, h5 a.toc-backref, 
+h6 a.toc-backref { 
+  color: #000000;
+}
+
+h1.title {
+  text-align: center;
+}
+
+table.footnote {
+  padding-left: 0.5ex;
+}
+
+table.citation {
+  padding-left: 0.5ex
+}
+
+pre.literal-block, pre.doctest-block {
+  border: thin black solid;
+  background-color: #ffffdf;
+  padding: 5px;
+}
+
+.image img { border-style : solid;
+            border-width : 2px;
+}
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+  font-size: 100%;
+}
+
+code, tt {
+  color: #000066;
+}
+
+kbd {
+  color: #101010;
+}

doc/manual.style → doc/assets/manual.style

@@ -7,7 +7,7 @@
         "frames": [
             ["0cm", "0cm", "100%", "100%"]
           ],
-        "background" : "biohazard.pdf",
+        "background" : "assets/biohazard-cover.pdf",
         "showHeader" : false,
         "showFooter" : false
     }

doc/gen_docs.sh

@@ -1,4 +1,14 @@
 #!/bin/sh
 
-rst2pdf manual.rst -o manual.pdf -s manual.style -b1
-rst2man rst2pdf.rst rst2pdf.1
+rst2pdf manual.rst --custom-cover=assets/cover.tmpl -o output/pdf/manual.pdf -s assets/manual.style -b1
+
+# Determine correct name for rst2man
+RST2MAN="rst2man"
+if [ -x "$(command -v rst2man.py)" ]; then
+    RST2MAN="rst2man.py"
+fi
+$RST2MAN rst2pdf.rst output/rst2pdf.1
+
+# set PYTHONPATH so we use the current contents of this repo, rather than our installed rst2pdf
+PYTHONPATH=../ python rst2html-manual.py --stylesheet=assets/manual.css manual.rst output/html/manual.html
+cp assets/biohazard.png output/html/assets/

doc/manual.rst

@@ -80,7 +80,7 @@ The user's file at ``~/.rst2pdf/config`` will have priority over the system's at
 Here's an example file showing some of the currently available options:
 
 .. code-block:: ini
-   :include: config.sample
+   :include: assets/config.sample
 
 Pipe usage
 ==========
@@ -154,11 +154,11 @@ You can insert images in the middle of your text like this::
 
   This |biohazard| means you have to run.
 
-  .. |biohazard| image:: ../rst2pdf/tests/input/images/biohazard.png
+  .. |biohazard| image:: assets/biohazard.png
 
 This |biohazard| means you have to run.
 
-.. |biohazard| image:: ../rst2pdf/tests/input/images/biohazard.png
+.. |biohazard| image:: assets/biohazard.png
 
 This only works correctly with reportlab 2.2 or later.
 
@@ -1074,14 +1074,14 @@ the options are:
 Let's display a class from rst2pdf::
 
       .. code-block:: python
-         :include: ../rst2pdf/flowables.py
+         :include: assets/flowables.py
          :start-at: class Separation(Flowable):
          :end-before: class Reference(Flowable):
 
 this command gives
 
 .. code-block:: python
-    :include: ../rst2pdf/flowables.py
+    :include: assets/flowables.py
     :start-at: class Separation(Flowable):
     :end-before: class Reference(Flowable):
 
@@ -1280,7 +1280,9 @@ use the ``--raw-html`` command line option.
 The counter role
 ================
 
-This is a nonstandard interpreted text role, which means it will only work with rst2pdf. It implements an unlimited number of counters you can use in your text.
+.. note:: The counter role only works in PDF, if you're reading the HTML version of the manual then this section is broken. Sorry :/
+
+This is a nonstandard interpreted text role, which means it will only work with ``rst2pdf``. It implements an unlimited number of counters you can use in your text.
 For example, you could use it to have numbered figures, or numbered tables.
 
 The syntax is this:
@@ -1379,17 +1381,6 @@ as text, the math role embeds an image. That means:
 
 So, use it only in emergencies ;-)
 
-You can also use an inline substitution of the math directive for things you use often,
-which is the same as using the math role::
-
-    This is the square of x: |xsq|
-
-    .. |xsq| math:: x^2
-
-This is the square of x: |xsq|
-
-.. |xsq| math:: x^2
-
 You don't need to worry about fonts, the correct math fonts will be used and embedded in
 your PDF automatically (they are included with matplotlib).
 

doc/output/.gitignore

@@ -0,0 +1 @@
+*

doc/rst2html-manual.py

@@ -0,0 +1,32 @@
+#!/usr/bin/python
+
+# $Id: rst2html.py 4564 2006-05-21 20:44:42Z wiemann $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+A minimal front end to the Docutils Publisher, producing HTML.
+"""
+
+try:
+    import locale
+    locale.setlocale(locale.LC_ALL, '')
+except:
+    pass
+
+from docutils.core import publish_cmdline, default_description
+from docutils.parsers.rst import directives
+import rst2pdf.pygments_code_block_directive
+directives.register_directive('code-block', rst2pdf.pygments_code_block_directive.code_block_directive)
+
+from docutils.parsers.rst import roles
+import rst2pdf.counter_off_role
+roles.register_canonical_role('counter', rst2pdf.counter_off_role.counter_fn) 
+
+import rst2pdf.noop_directive
+directives.register_directive('oddeven', rst2pdf.noop_directive.noop_directive)
+
+description = ('Generates (X)HTML documents from standalone reStructuredText '
+               'sources.  ' + default_description)
+
+publish_cmdline(writer_name='html', description=description)

rst2pdf/counter_off_role.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+from docutils.nodes import Text, target
+
+def counter_fn(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    return [], []
+
+counter_fn.content=False
+
+from docutils.parsers.rst import roles
+roles.register_canonical_role('counter', counter_fn)

rst2pdf/noop_directive.py

@@ -0,0 +1,8 @@
+from docutils.parsers import rst
+
+def noop_directive(name, arguments, options, content, lineno,
+                 content_offset, block_text, state, state_machine):
+    node_list = []
+    return node_list
+
+noop_directive.content = ["*"]