Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Stardust/ContributingDocumentation"

m
m (Hello World Template Documentation Plug-in)
Line 151: Line 151:
 
<p>You find an example documentation plug-in *org.eclipse.stardust.docs.template* containing all required files with example content. The example content uses the Stardust Doc style.</p>
 
<p>You find an example documentation plug-in *org.eclipse.stardust.docs.template* containing all required files with example content. The example content uses the Stardust Doc style.</p>
 
[[Image:doc-template.png]]
 
[[Image:doc-template.png]]
<p>You can view this example content or you can use it as basis for your new documentation plug-in. To use it as basis you can simply copy the plug-in and adjust it to your documentation. In that case take care to rename all occurrences of the plug-in name in the all plugin files.</p>
+
<p>You can view this example content or you can use it as basis for your new documentation plug-in. To use it as basis you can simply copy the plug-in and adjust it to your documentation. In that case take care to rename all occurrences of the plug-in name in all plugin files.</p>
 +
 
 
== Creating an Example Documentation Plug-in ==
 
== Creating an Example Documentation Plug-in ==
 
<p>In this example, we create a documentation plug-in with the steps described in the previous sections. The plug-in will contain example content and uses the Stardust documentation stylesheet.</p>
 
<p>In this example, we create a documentation plug-in with the steps described in the previous sections. The plug-in will contain example content and uses the Stardust documentation stylesheet.</p>

Revision as of 06:39, 26 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

    Create-project.png

  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.

    Enter-proj-details.png

  5. Click Next

  6. In the Content dialog click Next

    Create-plugin-data.png

  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

    Select-template.png

  9. Click Next

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

    Create-plugin-sample.png

Editing the Documentation Plug-in

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

New-project-tree.png

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.

Created-toc.png

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.:

New-project-tree-edited.png

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"

Edited-toc.png

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.

    Doc-feature-add.png

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

    Doc-feature-select.png

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

    Doc-feature-added.png

  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

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>

Hello World Template Documentation Plug-in

You find an example documentation plug-in *org.eclipse.stardust.docs.template* containing all required files with example content. The example content uses the Stardust Doc style.

Doc-template.png

You can view this example content or you can use it as basis for your new documentation plug-in. To use it as basis you can simply copy the plug-in and adjust it to your documentation. In that case take care to rename all occurrences of the plug-in name in all plugin files.

Creating an Example Documentation Plug-in

In this example, we create a documentation plug-in with the steps described in the previous sections. The plug-in will contain example content and uses the Stardust documentation stylesheet.

Creating the Plug-in

Create a new plug-in project as described in section Creating a new Plug-in Project. Name the plug-in org.eclipse.stardust.docs.mydocs and use the template Plug-in with sample help content.

Editing the toc.xml File

Now edit the toc.xml file and add the following link to the main toc entry:

<toc label="Enter your main Documentation Label ..." link_to="PLUGINS_ROOT/org.eclipse.stardust.docs.dev/toc.xml#additional_handbooks">

Adding some custom Documentation

Edit the toc.html file and enter some custom documentation and links to the maintopic.html and subtopic.html files.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <title>Hello World Example</title>
</head>

<body>
<h1>Hello World Example</h1>
<ul>
   <li><a href="maintopic.html">Main Topic</a>
   <ul>
      <li><a href="subtopic.html">Sub Topic</a></li>
   </ul></li>
</ul>
</body>
</html>

Adding the Plug-in to the Documentation Feature

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

Preparing a Local Documentation Build

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 your new documentation included in the Table of Contents section.

Resulting-toc.png

Back to the top