Difference between revisions of "Stardust/ContributingDocumentation"

Latest revision as of 04:55, 27 November 2015

Stardust Documentation Git Repository

To contribute to our Stardust documentation you need to check out the documentation git repository from the desired branch.

The documentation git repository is git.eclipse.org/c/stardust/org.eclipse.stardust.documentation.git.

Please refer to our Source Code and Contributing via Gerrit Wiki pages for details on how to clone and check out Stardust git repositories.

The Stardust documentation consists of several documentation plug-ins, which are linked to the main documentation. You can easily contribute to our documentation by adding or linking a custom documentation plug-in.

If you already have a local documentation plug-in you like to link into Stardust documentation, proceed with Linking a Documentation Plug-in to Stardust Documentation.

If you have documentation you like to put into a documentation plug-in to be linked into Stardust documentation, you need to create a plug-in project, in which you create or copy your documentation. Proceed with Creating a new Documentation Plug-in in that case.

Creating a new Documentation Plug-in

Creating a new Plug-in Project

To create a new plug-in project:

1. Select New & Project & Plug-in Project

   
   
   

2. Click Next

3. Enter a project name, e.g. org.eclipse.stardust.docs.mydocs

4. In the Location field enter the location of your checked out stardust/documentation followed by the plug-in name.

   
   
   

5. Click Next

6. In the Content dialog click Next

   
   
   

7. Select the Create a plug-in using one of the templates option

8. In the Available templates section select Plug-in with sample help content

   
   
   

9. Click Next

10. In the Sample Help Table of Contents dialog, select Primary and add an appropriate label.

    
    
    

Editing the Documentation Plug-in

Now you see the new plug-in in your workspace.

You find example html files added in the html folder. These files are linked from the toc.xml table of contents file and serve as examples to demonstrate the plug-in structure and toc usage.

Remove the example html files and add your custom documentation. Edit the toc.xml and replace the topics with your custom documentation topics and subtopics. As the main topic is linked to the main documentation topic, create a separate parent topic for it in the toc.xml file, e.g.:

Linking a Documentation Plug-in to Stardust Documentation

Linking the Plug-in to the main Documentation

The main documentation plug-in is org.eclipse.stardust.docs.dev. It contains an anchor additional_handbooks in the main toc.xml file. All additional documentation toc files can be linked to this anchor.

To link your documentation plug-in to the Stardust Documentation, enter the following link_to entry to the top toc line in your toc.xml file:

link_to="PLUGINS_ROOT/org.eclipse.stardust.docs.dev/toc.xml#additional_handbooks"

Linking the Plug-in to specific Handbooks or Topics

If you like to extend existing documentation handbooks or topics in handbooks, use specific anchors provided for those.

The tochandbooks.xml file in the main documentation plugin provides such specific anchors, where you can link your toc.xml file to. For the time being the following anchors are available:

• inttoc: for general integration guides
• intdatatoc: for Data Type integrations
• intappltoc: for Application Type integrations
• intprogtoc: for extensions in the Programming guide
• furtherProductGuides: for further developer product guides
• tocsecex: for Authentication examples (currently used to link authentication examples removed from Stardust)

To link your toc to one of these anchors in the tochandbooks.xml file, add the following link_to option to your toc.xml file:

<toc label="Your Plugin Title" link_to="PLUGINS_ROOT/ag.carnot.docs.dev/tochandbooks.xml#anchorid">

Including the Documentation Plug-in in the Stardust Documentation Feature

To include your new documentation plug-in in the documentation feature, edit the org.eclipse.stardust.documentation.documentation-feature feature plug-in and add your plug-in as follows:

1. In the Plug-ins and Fragments view, click the Add button.

   
   
   

2. In the upcoming dialog select your documentation plug-in.

   
   
   
3. Click OK

4. You can now see your documentation plug-in in the list of packaged plug-ins.

   
   
   
5. Save the change

You find the following entry containing your documentation plug-in id added to the features.xml file:

   <plugin
         id="org.eclipse.stardust.docs.mydocs"
         download-size="0"
         install-size="0"
         version="0.0.0"/>

Documentation Style

Please refer to the Eclipse Doc Style Guide for a general guide on Eclipse documentation styling.

To provide our Stardust documentation style, copy the styles folder, which you find in the following zip file, to the html folder of your documentation plug-in: styles.zip

This folder contains the carnot.css Stardust style sheet containing style classes for headers, lists etc. A subfolder images contains bullet images and the Stardust logo used in the first heading.

Linking to Topics in other Documentation Plug-ins

In some cases you might like to link to documentation residing in another documentation plug-in. This could be another plug-in provided by you or an existing one of Stardust. Eclipse provides a predefined variable PLUGINS_ROOT, which points to the root of all plug-ins of a feature. Use this variable in a link to another documentation plug-in, for example:

<a href="PLUGIN_ROOT/org.eclipse.stardust.docs.docplugin/html/toc.html">

General Styling Guideline

• A heading is always followed by body text (<p> html tag).
• All HTML tags should be overwritten with CSS styles only to keep consistency if a style changes
• Every book (e.g. installation) has as first "page" with an overview.
• Every added file must be referenced in the toc file (for Eclipse Help), residing in the according org.eclipse.stardust.docs.xxx or com.infinity.bpm.docs.xxx directory as well as in an according content overview html page.
• Use the <strong></strong> tag for menu items or names. (e.g. Click File > New > Project.)
• Use the <code></code> tag to display text for folder and file names (was <tt></tt> before and will be replaced as <tt>-tag is deprecated in HTML5)
• Use the <pre></pre> tag for code snippets.
• Anchors: use id="xy" to set anchors (e.g. <h2 id="heading2">Heading 2</h2>)
• Take care to use ascii for < and > (< and >) as otherwise they won't be rendered in most browsers.
• Take care to use clean html. For example missing out the <ul> tag surrounding <li> list entries results in using a default bullet image instead of the one declared in the stylesheet (for the <ul> tag).
• Spelling - we use American English spell check.

Adding a POM File

In your new documentation plug-in, add a pom.xml file with the following content:

    <?xml version="1.0" encoding="UTF-8"?><!--
        Copyright (c) 2012 SunGard CSA LLC and others.
        All rights reserved. This program and the accompanying materials
        are made available under the terms of the Eclipse Public License v1.0
        which accompanies this distribution, and is available at
        _http://www.eclipse.org/legal/epl-v10.html
       
        Contributors:
           SunGard CSA LLC - initial API and implementation and/or initial documentation
     -->

    <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
       xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <modelVersion>4.0.0</modelVersion>

       <parent>
          <groupId>org.eclipse.stardust.documentation</groupId>
          <artifactId>documentation-parent</artifactId>
          <version>9.9.9-SNAPSHOT</version>
          <relativePath>../pom.xml</relativePath>
       </parent>

       <artifactId>org.eclipse.stardust.docs.name</artifactId>

       <packaging>eclipse-plugin</packaging>

       <build>
          <plugins>
             <plugin>
                <groupId>org.eclipse.tycho</groupId>
                <artifactId>tycho-packaging-plugin</artifactId>
                <version>${tycho.version}</version>
                <configuration>
                   <additionalFileSets>
                      <fileSet>
                         <directory>${project.build.outputDirectory}</directory>
                         <includes>
                            <include>html/**/*</include>
                         </includes>
                      </fileSet>
                      <fileSet>
                         <directory>${project.build.directory}/overlay-resources</directory>
                         <excludes>
                            <exclude>**/*.properties.orig</exclude>
                            <exclude>**/*.xml.orig</exclude>
                         </excludes>
                      </fileSet>
                   </additionalFileSets>
                </configuration>
             </plugin>
          </plugins>
          <pluginManagement>
             <plugins>
                <plugin>
                   <groupId>org.apache.maven.plugins</groupId>
                   <artifactId>maven-resources-plugin</artifactId>
                   <version>2.5</version>
                </plugin>
             </plugins>
          </pluginManagement>
       </build>

    </project>

Using the Stardust Template Documentation Plug-in

You find an example documentation plug-in 'org.eclipse.stardust.docs.template' here: org.eclipse.stardust.docs.template.zip.

This example plug-in contains all required files with example content and uses the Stardust documentation style.

You can view this example content or you can use it as a basis for your new documentation plug-in. To use the plug-in as basis, extract the zip file to the location of your checked-out stardust documentation. Adjust it to your documentation. Take care to rename all occurrences of the plug-in name in all plugin files.

Creating a Hello World Example Documentation Plug-in

In this example, we create a documentation plug-in with the example documentation plug-in described in the previous section.

To start, download the example documentation plug-in org.eclipse.stardust.docs.template here: org.eclipse.stardust.docs.template.zip.

Copy the plug-in to the location of your checked-out stardust documentation.

Editing the toc.xml File

Edit the toc.xml file and add the following link to the main documentation toc entry:

<toc label="Hello World Example" link_to="PLUGINS_ROOT/org.eclipse.stardust.docs.dev/toc.xml#additional_handbooks">

Viewing the main Overview

Edit the toc.html file. You see links to the two example pages example-page-1.html and example-page-2.html.

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" type="text/css" href="styles/carnot.css" title="Style">
<!-- 
   Use the provided stylesheet in this example, or link to the stylesheet in
   the main documentation plugin:
   <link rel="stylesheet" type="text/css" href="PLUGINS_ROOT/org.eclipse.stardust.docs.dev/html/styles/carnot.css" title="Style">
-->
<title>Hello World Example</title>
</head>
<body>
<h1>Hello World Example</h1>
<ul>
   <li><a href="example-page-1.html">Example Page 1</a></li>
   <li><a href="example-page-2.html">Example Page 2</a></li>
</ul>
</body>
</html>

Adding the Plug-in to the Documentation Feature

Add the template plug-in to the documentation feature as described in section Including the Documentation Plug-in in the Stardust Documentation Feature.

Viewing the integrated Hello World Example Documentation

Now we prepare a local documentation build to see our new plug-in added to the documentation.

Please refer to section Build Stardust of our Source Code Wiki page for details on how to build a local eclipse update site. Start Eclipse and install the created update site accordingly.

Open the Eclipse Help via Help > Help Contents and select Stardust Documentation. See the Hello World Example documentation included in the Table of Contents section.