1.2. How To Build Sunflower Documentaion¶
Author: | Jim Klo <jim.klo@sri.com> |
---|
Table of Contents
1.2.1. Prerequisites¶
Apache Maven http://maven.apache.org/
Java SDK 1.8 http://www.oracle.com/technetwork/java/javase/downloads/index.html
Note
Update your
~/.mavenrc
set theJAVA_HOME
environment variable to the Java SDK 1.8 location if Java 1.8 is NOT your default JAVA SDK.Graphviz v2.38.x http://graphviz.org
(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¶
First update your homebrew installation.
$> brew update $> brew upgrade
Note
This can take a very long time depending upon the frequency of your update.
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
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
Now install this version of Graphviz
$> brew install graphviz
Check the installed version
$> dot -V dot - graphviz version 2.38.0 (20140413.2041)
Installation complete
1.2.1.1.2. Using msiexec on Windows 10¶
Download version 2.38 from Graphviz. Open your web browser to the following URL:
After the file has downloaded, run a command prompt as administrator and use
msiexec
to install. Open the Windows menu and typecmd
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
.Add Graphviz
bin
to your path. Opent the Windows menu and typesystem environment variables
. You should see the control panel Edit the system environment variables in the results list. Click that item to launch.The System Properties dialog window will open to the Advanced tab. On the lower right of the window, click the Environment Variables... button.
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.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
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.
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:
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 seecom/sri/sunflower-server
undersunflower-local
. If any of this doesn’t work, you need to request access via one of the project managers.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.
Create Maven settings file:
In this folder, copy the file
maven-settings-sample.xml
tomaven-settings.xml
. Editmaven-settings.xml
to include your own E-number and the encrypted password copied in step 2. above. You may then copy or merge the filemaven-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 | <source root>/doc/sunflower-manual/target/build/latex |
|
Sunflower Studio | HTML | <source root>/doc/sunflower-manual/target/build/html |
Developer | <source root>/doc/developer-docs/target/build/latex |
|
Developer | HTML | <source root>/doc/developer-docs/target/build/html |
Flora Tutorial | <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.