THIS REPOSITORY IS DEPRECATED

See https://github.com/aside-ufba/guide-automator for further development

GuideAutomator

Automated User Guide Generation with Markdown

• Installation
  • Prerequisites
  • Linux
  • Windows
• Getting started
  • Description
  • Example
  • Css selector
  • Firefox extension
• Usage
• Api commands
• Using GD.driver
• Author
  • Contributors

---

Installation

---

Prerequisites

• Nodejs && npm (Compiler)
• ImageMagick (Needed for cropping images)
• Wkhtmltopdf (Needed for converting html to pdf)
• Chrome and Chrome WebDriver (Selenium Web Browser automation)

back to top

Linux

• (Option 1)You can install with script

  sudo wget -qO- https://raw.githubusercontent.com/welbert/guide-automator/master/install_linux.sh | bash -

• (Option 2) Manual installation. You need install some binary dependencies.

  1.Node and npm:

    https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions
  

  2.ImageMagick (Usually is already installed):

    https://www.imagemagick.org/script/binary-releases.php#unix
  

  3.Wkhtmltopdf

    http://wkhtmltopdf.org/downloads.html
  

  4.Chrome/Chromium Browser

  -Chrome:
    https://www.google.com/chrome/browser/desktop/index.html
  -Chromium:
    sudo apt-get install chromium-browser
  

  5.Chrome WebDriver

    https://chromedriver.storage.googleapis.com/index.html?path=2.25/
  

  6.Guide-Automator

    sudo npm install -g guide-automator
  

Node, wkhtmltopdf and Chrome WebDriver need to be add in path.

back to top

Windows

1.Node and npm:

  https://nodejs.org/en/download/

2.ImageMagick: (Check to install legacy utilities)

  https://www.imagemagick.org/script/binary-releases.php#windows

3.Wkhtmltopdf

  http://wkhtmltopdf.org/downloads.html

4.Chrome

-Chrome:
  https://www.google.com/chrome/browser/desktop/index.html

5.Chrome WebDriver

  https://chromedriver.storage.googleapis.com/index.html?path=2.25/

6.Guide-Automator

  npm install -g guide-automator

Node, ImageMagick(convert.exe), Wkhtmltopdf and Chrome WebDriver need to be add in path.

back to top

---

Getting started

---

Description

Guide-automator extract javascript tags (```javascript guide-automator commands ```) from markdown file and generate manual from them. You need use our API commands in markdown file.

back to top

Example:

# This is my github

```javascript
  get('https://github.com/welbert');
  takeScreenshot();
  takeScreenshotOf('.avatar',false,true);

```(<- three back-ticks)

More examples with comments here or see raw, if you want to look the output pdf (This pdf was created using command '$ guide-automator -i examples/example.md -o output/ -s lightBlue')

back to top

Css selector

You will need know how to extract css selector of Web elements, you can use the browser to do that. If you dont know how to do this, see below.

• Google Chrome

• Mozilla Firefox

After this steps, the css selector will be copied to your clipboard

back to top

---

Firefox extension

---

You can use the firefox addon to make easy the construction of blocks

Guide-automator-addon

back to top

---

USAGE

---

$ guide-automator -h

  Usage: guide-automator [options]

  Options:


    -h, --help             output usage information
    -V, --version          output the version number
    -i, --input <File.md>  Input .md file
    -o, --output <Folder>  Output destination folder
    -P, --pdf              Export manual to PDF, default is export for all types
    -H, --html             Export manual to HTML, default is export for all types
    -I, --image            Export ONLY manual's image and ignore others types, default is export for all types
    -s, --style <style.css>  Css style to be used in the manual or theme [lightBlue,lightOrange]
    -d, --debug              Show progress of code

  Examples:

    $ guide-automator -i input.md -o output/
    $ guide-automator -i input.md
    $ guide-automator -i input.md -o output/ -s lightBlue

back to top

---

API commands

---

Params: <Required> [Optional]

• get
• click
• clickByLinkText
• takeScreenshot
• takeScreenshotOf
• fillIn
• submit
• wait
• sleep
• console.print
• pageContext

get

• Description: Url to access
• Params: <url>
• Example:
  • get('https://github.com/welbert');

click

• Description: Click on element
• Params: <cssSelector>
• Example:
  • click('.unstarred > button:nth-child(2)');

clickByLinkText

• Description: Click on link text(<a>)
• Params: <linkText>
• Example:
  • clickByLinkText('README.md');

takeScreenshot

• Description: Take Screenshot
• Params: [imageWidth]
• Example:
  • takeScreenshot();
  • takeScreenshot('10%');

takeScreenshotOf

• Description: Take Screenshot of specific element
• Params: <cssSelector>, [crop], [outline], [imageWidth]
• Params: Array(<cssSelector>,[cssSelector],...), [crop], [outline], [imageWidth]
• Params: Array(Array(<cssSelector>,<Iframe-CssSelector>),[cssSelector],...), [crop], [outline], [imageWidth]
• Example:
  • takeScreenshotOf('#user-content-guideautomator');
  • takeScreenshotOf('#user-content-guideautomator',false,true);
  • takeScreenshotOf(['#user-content-guideautomator','.avatar'],false,true); //Multiple cssSelector(only for outline)
  • takeScreenshotOf([['#user-content-guideautomator','#frameID'],'.avatar'],false,true) //Multiple cssSelector (only for outline) on different contexts(Iframe)

fillIn

• Description: Fill in field element
• Params: <cssSelector>, <input>
• Example:
  • fillIn('.header-search-input','guide-automator');

submit

• Description: Submit a form
• Params: <cssSelector>
• Example:
  • submit('.js-site-search-form');

wait

• Description: Wait element load on page
• Params: <cssSelector>, [timeOut]
• Example:
  • wait('.commit-author-section');
  • wait('.commit-author-section',2000);

sleep

• Description: Sleep for a while
• Params: <milleseconds>
• Example:
  • sleep(1000);

console.print

• Description: Print text on markdown file using javascript blocks
• Params: <text>
• Example:
  • console.print('# Title');

pageContext

• Description: Need to change context to iframe or context default(Main page)
• Params: [cssSelector]
• Example:
  • pageContext('#Iframe-CssSelector');
  • pageContext('default'); //Equivalent to pageContext();
  • pageContext();

back to top

---

Using GD.driver

---

This topic is for more complex cases or personal needs that guide-automator does not support

Example:

GD.driver.actions().
  mouseMove({x:216, y:41}).
  click().
  perform();

See raw

Selenium Documentation

back to top

Author

Allan Oliveira

Contributors

• Welbert Serra

back to top