1.2. How To Build Sunflower Documentaion

Author:Jim Klo <jim.klo@sri.com>

1.2.1. Prerequisites

  1. Apache Maven http://maven.apache.org/

  2. Java SDK 1.8 http://www.oracle.com/technetwork/java/javase/downloads/index.html

    Note

    Update your ~/.mavenrc set the JAVA_HOME environment variable to the Java SDK 1.8 location if Java 1.8 is NOT your default JAVA SDK.

  3. Graphviz v2.38.x http://graphviz.org

  4. (Optional) LaTeX https://www.latex-project.org - only needed to build PDF versions.

1.2.1.1. Installing Graphviz

The documentation utilized PlantUML in some places to generate diagrams. PlantUML depends upon having Graphviz installed, however there is a bug in the latest version that causes some issues with PlantUML rendering. The most recent known version of Graphviz known to work is 2.38.0.

1.2.1.1.1. Using Homebrew on macOS

  1. First update your homebrew installation.

    $> brew update
    $> brew upgrade
    

    Note

    This can take a very long time depending upon the frequency of your update.

  2. Check to see if graphviz is installed.

    $> dot -V
    

    If the command is not found, then you can continue to the next step. If the version installed is newer than version 2.38.0, then you must install a downgraded version. To begin this process:

    $> brew unlink graphviz
    
  3. Fetch the last know good Formula for Graphviz 2.38.0.

    $> cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula
    $> git checkout 7a4dabfc1a2acd9f01a1670fde4f0094c4fb6ffa graphviz.rb
    
  4. Now install this version of Graphviz

    $> brew install graphviz
    
  5. Check the installed version

    $> dot -V
    dot - graphviz version 2.38.0 (20140413.2041)
    
  6. Installation complete

1.2.1.1.2. Using msiexec on Windows 10

  1. Download version 2.38 from Graphviz. Open your web browser to the following URL:

  2. After the file has downloaded, run a command prompt as administrator and use msiexec to install. Open the Windows menu and type cmd into the search bar. You should see the Windows Application Command Prompt icon in the results. Right-click on the Command Prompt icon, and then click Run as administrator.

    Warning

    For some versions of Windows, double clicking the MSI package, even when logged in as Adminstrator does not install this package correctly.

    C:\Windows\system32> cd C:\Users\user1\Downloads
    C:\Users\user1\Downloads> msiexec /a graphviz-2.38.msi
    

    This will launch the Graphviz installer. You can click Next on each of the screens to accept the default install. This will install Graphviz into C:\Program Files (x86)\Graphviz2.38.

  3. Add Graphviz bin to your path. Opent the Windows menu and type system environment variables. You should see the control panel Edit the system environment variables in the results list. Click that item to launch.

  4. The System Properties dialog window will open to the Advanced tab. On the lower right of the window, click the Environment Variables... button.

  5. The Environment Variables dialog window will now open. On the bottom half of this window, is the System variables pane containing a list of defined system variables. Locate and highlight the Path system variable using a single-click. Then click the Edit... button below.

  6. The Edit environment variable dialog will now open. Click the New button, then add the path to Graphviz bin to the text field. If you accepted a default installation of Graphviz, you should type:

    C:\Program Files (x86)\Graphviz2.38\bin
    
  7. Click the OK button to close the edit dialog, then click OK to close the Environment Variables dialog, then click OK to close the System Properties dialog.

  8. Installation complete.

1.2.2. Overview

The documentation compiler utilizes the Sunflower Foundation library to match the syntax highlighting of Flora2 in the same manner as displayed when using the Sunflower Studio editor. In order to do this, the documentation is built using Jython, Sphinx, and a custom syntax highligher for Pygments

1.2.3. Checkout Documentation Sources

Sunflower Documentation has it’s own source repository. You can clone the source using the following command:

git clone https://<username>@scm.sri.com/scm/git/ROR/sunflower-docs

replacing <username> with your SRI LDAP Username or SRI provided username for external users.

1.2.4. Sunflower Foundation as a Dependency

As previously mentioned, Sunflower Foundation is used to assist in syntax highlighting of the Sunflower Documentation. You may choose to get this dependency by either building Sunflower Foundation with a mvn install or you may download the pre-built library from Artifactory. To build and install, refer to the documentation for Maven Quickstart Build: Sunflower Foundation. Once installed you can continue with these instructions.

If using Artifactory, you will need to configure your local Maven installation to use the SRI Artifactory server:

  1. Verify that you have access:

    Using your E-number/LDAP password, log in to https://artifactory.sri.com/artifactory/ and go to the “Artifacts” tab. In the list of repos, make sure sunflower-local shows up, and expand it. Make sure you see com/sri/sunflower-server under sunflower-local. If any of this doesn’t work, you need to request access via one of the project managers.

  2. Retrieve your encrypted password:

    Still in the Artifactory UI, click on your E-number in the upper right corner, enter your LDAP password again, and click “Unlock”. Copy the “Encrypted password” to your clipboard.

  3. Create Maven settings file:

    In this folder, copy the file maven-settings-sample.xml to maven-settings.xml. Edit maven-settings.xml to include your own E-number and the encrypted password copied in step 2. above. You may then copy or merge the file maven-settings.xml into your own settings file, most likely located at ~/.m2/settings.xml, or you can use the switch -s maven-settings.xml to peruse the settings for an individual call to Maven.

1.2.5. Installation of Documentation System

Assuming you have the Java SDK 1.8 and Apache Maven installed, you will need to install the documentation system. You only need to perform this step once.

$> cd <source root>/sunflower-docs/doc
$> mvn -Pinstall-sphinx-doc -DskipTests clean install

Note

If you have the Artifactory settings above in a settings file different than the default location such as ~/.m2/settings.xml, then add switch -s maven-settings.xml to the command above.

1.2.6. Building Documentation

Once the documentation system has been installed, the documentation can be built into both HTML and PDF versions. By default, both HTML and PDF versions are built which requires LaTeX to be installed and available on your path.

Both the Sunflower Studio and the Sunflower Developer documentation are built concurrently with the same command.

mvn clean package

Note

Alternative Builds

To build only HTML versions of the documentation:

mvn clean package -P \!build-pdf-docs

To build only PDF versions of the documentation:

mvn clean package -P \!build-html-docs

You can also build each set of documentation individually. To do this, just cd <documentation project> and use the same mvn clean package command and optional arguments described above.

For example, to build HTML versions of the Developer Documentation:

cd sunflower-developer-docs
mvn clean package -P \!build-pdf-docs

1.2.7. Build Output

After the documentation is built, the output can be found in the following locations:

Topic Type Location
Sunflower Studio PDF <source root>/doc/sunflower-manual/target/build/latex
Sunflower Studio HTML <source root>/doc/sunflower-manual/target/build/html
Developer PDF <source root>/doc/developer-docs/target/build/latex
Developer HTML <source root>/doc/developer-docs/target/build/html
Flora Tutorial PDF <source root>/doc/flora-tutorial-with-homework/target/build/latex
Flora Tutorial HTML <source root>/doc/flora-tutorial-with-homework/target/build/html

1.2.8. Note

Additional details for building Sunflower Documentation can be found inside the README.md file located within the cloned source.