Revision: f0be49698621
Branch: default
Author: Robot Framework Developers (robotframew...@gmail.com)
Date: Tue Oct 9 06:21:10 2012
Log: libdoc: support for reST format
Update issue 489
Added support for reStructuredText. Can be enabled with `--DocFormat reST`.
http://code.google.com/p/robotframework/source/detail?r=f0be49698621
Modified:
/atest/robot/libdoc/doc_format.txt
/atest/robot/libdoc/invalid_usage.txt
/atest/robot/libdoc/libdoc_resource.txt
/atest/testdata/libdoc/DocFormat.py
/src/robot/htmldata/libdoc/libdoc.css
/src/robot/libdoc.py
/src/robot/libdocpkg/htmlwriter.py
=======================================
--- /atest/robot/libdoc/doc_format.txt Tue Oct 9 04:16:44 2012
+++ /atest/robot/libdoc/doc_format.txt Tue Oct 9 06:21:10 2012
@@ -21,6 +21,14 @@
HTML format in HTML
Test Format in HTML -F html
... *bold* or <b>bold</b> ${EXAMPLE URL}
+
+reST format in HTML
+ [Setup] Make test non-critical if docutils is not installed
+ Test Format in HTML --docformat rest
+ ... <em>bold</em> or <b>bold</b> <a *>${EXAMPLE URL}</a>
+ ... Link to <cite>Keyword</cite>.
+ Doc Should Contain In HTML ${MODEL['keywords'][2]}
+ ... This link to <a href="#Keyword" class="name">Keyword</a>
Robot format in XML
Test Format In XML --DOCFORMAT RoBoT ROBOT
@@ -41,9 +49,12 @@
*** Keywords ***
Test Format In HTML
- [Arguments] ${options} ${expected}
+ [Arguments] ${options} ${expected1}
+ ... ${expected2}=Link to <a href="#Keyword"
class="name">Keyword</a>.
Run Libdoc And Parse Model From HTML ${options} ${LIBRARY}
- Doc Should Contain In HTML ${MODEL['keywords'][0]} ${expected}
+ Doc Should Contain In HTML ${MODEL} ${expected1}
+ Doc Should Contain In HTML ${MODEL['keywords'][0]} ${expected1}
+ Doc Should Contain In HTML ${MODEL['keywords'][1]} ${expected2}
Test Format In XML
[Arguments] ${options} ${expected}
@@ -54,3 +65,7 @@
Format should be
[Arguments] ${expected}
Element Attribute Should Be ${LIBDOC} format ${expected}
+
+Make test non-critical if docutils is not installed
+ ${output} = Run ${INTERPRETER} -c "import docutils; print 'OK'"
+ Run Keyword If """${output}""" != "OK" Remove Tags regression
=======================================
--- /atest/robot/libdoc/invalid_usage.txt Tue Oct 9 04:07:44 2012
+++ /atest/robot/libdoc/invalid_usage.txt Tue Oct 9 06:21:10 2012
@@ -26,7 +26,7 @@
BuiltIn out.ext Format must be 'HTML' or 'XML', got 'EXT'.
Invalid doc format
- --docformat inv BuiltIn out Doc format must be 'ROBOT', 'TEXT'
or 'HTML', got 'INV'.
+ --docformat inv BuiltIn out Doc format must
be 'ROBOT', 'TEXT', 'HTML' or 'REST', got 'INV'.
Non-existing library
NonExistingLib out.html Importing test library 'NonExistingLib'
failed: *
=======================================
--- /atest/robot/libdoc/libdoc_resource.txt Tue Oct 9 02:19:42 2012
+++ /atest/robot/libdoc/libdoc_resource.txt Tue Oct 9 06:21:10 2012
@@ -38,7 +38,7 @@
Doc Should Contain In HTML
[Arguments] ${object} ${expected}
- Should Contain ${object['doc']} ${expected}
+ Should Match ${object['doc']} *${expected}*
Name Should Be
[Arguments] ${name}
=======================================
--- /atest/testdata/libdoc/DocFormat.py Tue Oct 9 03:05:07 2012
+++ /atest/testdata/libdoc/DocFormat.py Tue Oct 9 06:21:10 2012
@@ -1,5 +1,32 @@
+"""Library to test documentation formatting.
-
+*bold* or <b>bold</b> http://example.com
+"""
def keyword():
"""*bold* or <b>bold</b> http://example.com""";
+
+def link():
+ """Link to `Keyword`."""
+
+def rest():
+ """Let's see *how well* reST__ works.
+
+ This documentation is mainly used for manually verifying reST output.
+ This link to \\`Keyword\\` is also automatically tested.
+
+ ==== =====
+ My table
+ two rows
+ ==== =====
+
+ - list
+ - here
+
+ Preformatted::
+
+ def example():
+ pass
+
+ __ http://docutils.sourceforge.net
+ """
=======================================
--- /src/robot/htmldata/libdoc/libdoc.css Wed May 30 14:52:44 2012
+++ /src/robot/htmldata/libdoc/libdoc.css Tue Oct 9 06:21:10 2012
@@ -38,7 +38,7 @@
border: 2px solid black;
border-collapse: collapse;
empty-cells: show;
- margin: 0.3em 0em;
+ margin: 0.3em 0;
width: 100%;
}
table.keywords th, table.keywords td {
@@ -61,3 +61,10 @@
.footer {
font-size: 0.9em;
}
+/* Docs originating from HTML and reST are wrapped to divs. */
+.doc div > *:first-child {
+ margin-top: 0;
+}
+.doc div > *:last-child { /* Does not work with IE8. */
+ margin-bottom: 0;
+}
=======================================
--- /src/robot/libdoc.py Tue Oct 9 04:16:44 2012
+++ /src/robot/libdoc.py Tue Oct 9 06:21:10 2012
@@ -141,7 +141,8 @@
def _get_doc_format(self, format):
if not format:
return None
- return self._verify_format('Doc format', format,
['ROBOT', 'TEXT', 'HTML'])
+ return self._verify_format('Doc format', format,
+ ['ROBOT', 'TEXT', 'HTML', 'REST'])
def _get_output_format(self, format, output):
default = os.path.splitext(output)[1][1:]
=======================================
--- /src/robot/libdocpkg/htmlwriter.py Tue Oct 9 03:05:07 2012
+++ /src/robot/libdocpkg/htmlwriter.py Tue Oct 9 06:21:10 2012
@@ -15,6 +15,7 @@
import os
import re
+from robot.errors import DataError
from robot.htmldata import HtmlFileWriter, ModelWriter, JsonWriter, LIBDOC
from robot import utils
@@ -122,7 +123,8 @@
def __init__(self, format):
self._formatter = {'ROBOT': utils.html_format,
'TEXT': self._format_text,
- 'HTML': self._format_html}[format]
+ 'HTML': self._format_html,
+ 'REST': self._format_rest}[format]
def _format_text(self, doc):
return '<p style="white-space: pre-wrap">%s</p>' %
utils.html_escape(doc)
@@ -130,5 +132,13 @@
def _format_html(self, doc):
return '<div style="margin: 0">%s</div>' % doc
+ def _format_rest(self, doc):
+ try:
+ from docutils.core import publish_parts
+ except ImportError:
+ raise DataError("reST format requires 'docutils' module to be
installed.")
+ parts = publish_parts(doc, writer_name='html')
+ return self._format_html(parts['html_body'])
+
def __call__(self, doc):
return self._formatter(doc)
