Skip to content
CUBA Platform Documentation
Branch: master
Clone or download
Pull request Compare This branch is 27 commits ahead, 18 commits behind cuba-platform:master.
Latest commit a4ecd67 Jun 2, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update issue_template.md Apr 2, 2018
buildSrc no message Mar 31, 2019
content fix conflict Jun 2, 2019
gradle/wrapper Change copyright year, release notes, gradle wrapper version Dec 12, 2017
images Add Edit on GitHub button cuba-platform#166 Aug 31, 2018
js
polymer-build merge latest May 30, 2019
styles
tools merge latest May 30, 2019
.gitignore Add deploy tasks, fix up-to-date checks Mar 5, 2018
.project merge latest May 30, 2019
LICENSE.md Add CC BY license Mar 5, 2018
README.md Build version 7.0 Oct 29, 2018
build.gradle merge latest May 30, 2019
gradlew
gradlew.bat Add Gradle Wrapper Oct 20, 2017
settings.gradle

README.md

CUBA Platform Documentation

Overview

The documentation is written in AsciiDoc format. Source files, images and includes are located in the content directory in the following subdirectories:

  • manual - Developer's Manual
  • polymer - Polymer UI Tutorial
  • release_notes - latest release notes
  • other subdirectories contain documentation on platform addons.

Most of the documents have English and Russian versions in the corresponding subdirectories (en and ru).

Released documentation is available at CUBA website.

Building from Source

Prerequisites

In order to produce HTML from AsciiDoc, we use Asciidoctor. It can be installed as follows:

  1. Install Ruby (tested on version 2.1).

  2. Install Asciidoctor:

     gem install asciidoctor -v 1.5.2
    
  3. Install coderay for code highlighting:

     gem install coderay
    

This is enough to build the documentation with the existing visual theme. If you want to change the theme, see the Building Theme section below.

Build Tasks

Gradle is used as a build tool. Build task names have the following structure: {purpose}{doc}{lang}.

{purpose} can be one of the following:

  • build - build single-HTML document.
  • chop - build multi-page document.
  • war - build a WAR file. The resulting WAR file will have a name corresponding to the document name and a version which is set by the ext.docVersion property defined in build.gradle, for example manual-7.0.war.
  • deploy - deploy WAR to Tomcat (installed by the setupTomcat task, see below).

{doc} is the document name (Manual, Bpm, etc.)

{lang} can be either En or Ru.

For example, to build and deploy the English manual, use the following command:

./gradlew deployManualEn

Before running the deploy task, install the local Tomcat server by executing the following task:

./gradlew setupTomcat

By default, Tomcat is installed into ./deploy/tomcat and configured to listen on port 6080.

Building Theme

The CSS file containing the theme is located in the styles directory. Don't change this file - it must be built by the AsciiDoc theme builder. The theme builder is located in the tools/asciidoctor-stylesheet-factory directory (it is a copy of the asciidoctor-stylesheet-factory project).

The theme source code is contained in two files: sass/cuba.scss and sass/settings/_cuba.scss. After making changes in these files, execute the buildCubaTheme Gradle task. As a result, a new cuba.css will be written to the styles directory.

The buildCubaTheme task requires the following Ruby gems:

gem install --no-rdoc --no-ri sass -v 3.4.22
gem install --no-rdoc --no-ri compass
gem install zurb-foundation

If you get an error like

C:/Program Files/Ruby21-x64/lib/ruby/gems/2.1.0/gems/compass-core-1.0.3/lib/compass/core/sass_extensions/functions/urls.rb:5:in `has?': undefined method `has?' for Sass::Util:Module (NoMethodError)
        from C:/Program Files/Ruby21-x64/lib/ruby/gems/2.1.0/gems/compass-core-1.0.3/lib/compass/core/sass_extensions/functions/urls.rb:9:in `included'
        from C:/Program Files/Ruby21-x64/lib/ruby/gems/2.1.0/gems/sass-3.5.0.pre.rc.1/lib/sass/script/functions.rb:632:in `include'

then try to uninstall gem sass-3.5.0.pre.rc.1 and install 3.4.22. Perhaps you should also reinstall all the other gems.

Viewing Documentation Locally

After installing Tomcat and deploying a document as described above, start the server:

./deploy/tomcat/bin/startup.sh 

If you build, for example, manual for version 7.0, it will be available at http://localhost:6080/manual-7.0.

You can’t perform that action at this time.