.. _build_documentation: *********************************** How To Build Sunflower Documentaion *********************************** :Author: Jim Klo .. contents:: Table of Contents 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. 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**. Using Homebrew on macOS ``````````````````````` 1. First update your homebrew installation. .. code-block:: bash $> 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. .. code-block:: bash $> 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: .. code-block:: bash $> brew unlink graphviz 3. Fetch the last know good Formula for Graphviz 2.38.0. .. code-block:: bash $> cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula $> git checkout 7a4dabfc1a2acd9f01a1670fde4f0094c4fb6ffa graphviz.rb 4. Now install this version of Graphviz .. code-block:: bash $> brew install graphviz 5. Check the installed version .. code-block:: bash $> dot -V dot - graphviz version 2.38.0 (20140413.2041) 6. Installation complete Using msiexec on Windows 10 ``````````````````````````` 1. Download version 2.38 from Graphviz. Open your web browser to the following URL: http://www.graphviz.org/pub/graphviz/stable/windows/graphviz-2.38.msi 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. .. code-block:: doscon 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. 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`_ Checkout Documentation Sources ============================== Sunflower Documentation has it's own source repository. You can clone the source using the following command: .. code-block:: bash git clone https://@scm.sri.com/scm/git/ROR/sunflower-docs replacing ```` with your SRI LDAP Username or SRI provided username for external users. 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 :ref:`quickstart-sf-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. 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. .. code-block:: sh $> cd /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. 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. .. code-block:: sh mvn clean package .. note:: Alternative Builds To build only HTML versions of the documentation: .. code-block:: bash mvn clean package -P \!build-pdf-docs To build only PDF versions of the documentation: .. code-block:: bash mvn clean package -P \!build-html-docs You can also build each set of documentation individually. To do this, just ``cd `` and use the same ``mvn clean package`` command and optional arguments described above. For example, to build HTML versions of the Developer Documentation: .. code-block:: sh cd sunflower-developer-docs mvn clean package -P \!build-pdf-docs Build Output ============ After the documentation is built, the output can be found in the following locations: +------------------+------+-----------------------------------------------------------------------+ | Topic | Type | Location | +==================+======+=======================================================================+ | Sunflower Studio | PDF | ``/doc/sunflower-manual/target/build/latex`` | +------------------+------+-----------------------------------------------------------------------+ | Sunflower Studio | HTML | ``/doc/sunflower-manual/target/build/html`` | +------------------+------+-----------------------------------------------------------------------+ | Developer | PDF | ``/doc/developer-docs/target/build/latex`` | +------------------+------+-----------------------------------------------------------------------+ | Developer | HTML | ``/doc/developer-docs/target/build/html`` | +------------------+------+-----------------------------------------------------------------------+ | Flora Tutorial | PDF | ``/doc/flora-tutorial-with-homework/target/build/latex`` | +------------------+------+-----------------------------------------------------------------------+ | Flora Tutorial | HTML | ``/doc/flora-tutorial-with-homework/target/build/html`` | +------------------+------+-----------------------------------------------------------------------+ Note ==== Additional details for building Sunflower Documentation can be found inside the README.md file located within the cloned source. .. _Java SDK 1.8: http://www.oracle.com/technetwork/java/javase/downloads/index.html .. _Apache Maven: http://maven.apache.org .. _Pygments: http://pygments.org .. _Sphinx: http://sphinx-doc.org .. _Jython: http://www.jython.org