Eight years ago when I graduated from the University my first job title was a QA Engineer. Lots have been changed since then, but these days I am once again facing some QA tasks. Gladly this time we are talking Test Automation.
In particular my team mates and myself are going to develop a set of test cases to automate acceptance and regressions testing for Nuage VSP products. For many reasons for this task we chose Robot Framework as a tool to write our test cases. Without going into the details about what are the benefits of Robot let me jump to the very point of this post.
Robot has one of the most comprehensive User Guides I’ve seen in Opensource world. It is well-written, descriptive, with lots of examples, but… But it lacks of modern formatting. It is hard to read the docs on a wide monitors, impossible to read on tablets/phones, code snippets have been formatted in too narrow elements and other visual stuff that prevents one to enjoy the documentation itself in full flavor.
Given that I made a humble attempt to
beautify the official User Guide of Robot by going the same way as I did with NokDoc — namely, using the Bootstrap CSS and automatically rebuild the docs with it.
Please meet rfug.github.io (rfug stands for robot framework user guide).
What has been changed?
- Layout now responsive, meaning it will adapt to your device resolution. You may enjoy RF User Guide on portable devices
- Open Sans font is enabled by default
- Tables are now 100% wide and with a cleaner look
I have also compiled a PDF version of the Bootstrapped User Guide. It has the same nice styles applied as well as Table Of Contents, so you will have the ability to navigate through the document quick & easy.
What could be added?
- I still have some things to fugure out how to make the page layout be more usable on small resolutions (phones)
- Sidebar with all the table of contents links
How it’s been done?
I wrote a small html parser powered by BeautifulSoup4 package to add/change the elements in original User Guide. And I uploaded it to the free HTML server of github (namely github pages).
from bs4 import BeautifulSoup
with open('Robot Framework User Guide.html', 'r', encoding='utf-8') as f, \
open('index.html', 'w', encoding='utf-8') as out:
soup = BeautifulSoup(f.read(), 'html.parser')
# adding bootstrap container class to the main document div
main_div = soup.find(id='robot-framework-user-guide')
main_div['class'] += ' container'
# fixing all href values to be domain agnostic
for a in soup.find_all('a'):
if '#' in a['href']:
a['href'] = '#' + a['href'].split('#', 1)
# create a link element and add it to the docs html element
bootstrap1 = soup.new_tag('link', rel='stylesheet', href='https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css')
# modify table styles
for table in soup.find_all('table'):
table['class'] = 'table table-condensed table-bordered'
for th in table.find_all('th'):
th['class'] = "active"
# create a text to add to H2 header
h2_add = '<br/><small>This is a mirror of the <a href="http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html">official</a> Robot Framework User Guide with Bootstrap CSS enabled. <br/>Created by <a href="https://www.linkedin.com/in/rdodin">Roman Dodin</a></small>'
h2 = soup.find(id='version-version')
# create additional style element for Open Sans font
style_add = """
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif !important;
# write the resulting document