Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Stardust/ContributingDocumentation"
m |
m |
||
| Line 10: | Line 10: | ||
linking a custom documentation plugin.</p> | linking a custom documentation plugin.</p> | ||
<p>If you already have a local documentation plugin you like to link into Stardust documentation, proceed with | <p>If you already have a local documentation plugin you like to link into Stardust documentation, proceed with | ||
| − | [[#Linking a Documentation Plugin to Stardust Documentation]].</p> | + | [[#Linking a Documentation Plugin to Stardust Documentation|Linking a Documentation Plugin to Stardust Documentation]].</p> |
| − | <p>If you have documentation you like to put into a documentation plugin to be linked into Stardust documentation, you need to create a plugin project, in which you create or copy your documentation. Proceed with [[#Creating a new Documentation Plugin]] in that case.</p> | + | <p>If you have documentation you like to put into a documentation plugin to be linked into Stardust documentation, you need to create a plugin project, in which you create or copy your documentation. Proceed with [[#Creating a new Documentation Plugin|Creating a new Documentation Plugin]] in that case.</p> |
== Creating a new Documentation Plugin == | == Creating a new Documentation Plugin == | ||
| Line 19: | Line 19: | ||
# <p>Select '''New & Project & Plug-in Project'''</p>[[Image:create-project.png]]<br><br> | # <p>Select '''New & Project & Plug-in Project'''</p>[[Image:create-project.png]]<br><br> | ||
# <p>Click '''Next'''</p> | # <p>Click '''Next'''</p> | ||
| − | # <p>Enter a project name, e.g. | + | # <p>Enter a project name, e.g. ''org.eclipse.stardust.docs.mydocs''</p> |
| − | # <p>In the '''Location''' field enter the location of your checked out <tt>stardust/documentation</tt> followed by the plugin name.</p>[[Image: | + | # <p>In the '''Location''' field enter the location of your checked out <tt>stardust/documentation</tt> followed by the plugin name.</p>[[Image:enter-proj-details.png]]<br><br> |
# <p>Click '''Next'''</p> | # <p>Click '''Next'''</p> | ||
| + | # <p>In the '''Content''' dialog click '''Next'''</p>[[Image:create-plugin-data.png]]<br><br> | ||
# <p>Select the '''Create a plug-in using one of the templates''' option</p> | # <p>Select the '''Create a plug-in using one of the templates''' option</p> | ||
# <p>In the '''Available templates''' section select '''Plug-in with sample help content'''</p>[[Image:select-template.png]]<br><br> | # <p>In the '''Available templates''' section select '''Plug-in with sample help content'''</p>[[Image:select-template.png]]<br><br> | ||
| Line 37: | Line 38: | ||
== Linking a Documentation Plugin to Stardust Documentation == | == Linking a Documentation Plugin to Stardust Documentation == | ||
| − | + | === Adding a Link to the main Documentation Plugin === | |
| + | The main documentation plugin 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. | ||
<p>To link your documentation plugin to the Stardust Documentation, enter the following | <p>To link your documentation plugin to the Stardust Documentation, enter the following | ||
| − | '''link_to''' entry to the top toc line:</p> | + | '''link_to''' entry to the top toc line in your ''toc.xml'' file:</p> |
| − | ''link_to="PLUGINS_ROOT/org.eclipse.stardust.docs.dev/toc.xml#additional_handbooks"'' | + | <p>''' ''link_to="PLUGINS_ROOT/org.eclipse.stardust.docs.dev/toc.xml#additional_handbooks"'' '''</p> |
[[Image:edited-toc.png]]<br><br> | [[Image:edited-toc.png]]<br><br> | ||
| + | === Including the Documentation Plugin in Documentation Features === | ||
== Style Guide == | == Style Guide == | ||
<p>Please refer to the [https://wiki.eclipse.org/Eclipse_Doc_Style_Guide Eclipse Doc Style Guide] for a general guide on Eclipse documentation styling.</p> | <p>Please refer to the [https://wiki.eclipse.org/Eclipse_Doc_Style_Guide Eclipse Doc Style Guide] for a general guide on Eclipse documentation styling.</p> | ||
| − | <p>To provide our Stardust documentation style, copy the following to the | + | <p>To provide our Stardust documentation style, copy the following to the '''html''' folder of your documentation plugin: |
[[media:styles styles]]</p> | [[media:styles styles]]</p> | ||
| − | <p>This folder contains the | + | <p>This folder contains the '''carnot.css''' Stardust style sheet containing style classes for |
| − | headers, lists etc. A subfolder | + | headers, lists etc. A subfolder '''images''' contains bullet images and the Stardust logo used in the first heading.</p> |
Revision as of 05:48, 18 November 2015
Contents
Contributing Documentation to Stardust
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 plugins, which are linked to the main documentation. You can easily contribute to our documentation by adding or linking a custom documentation plugin.
If you already have a local documentation plugin you like to link into Stardust documentation, proceed with Linking a Documentation Plugin to Stardust Documentation.
If you have documentation you like to put into a documentation plugin to be linked into Stardust documentation, you need to create a plugin project, in which you create or copy your documentation. Proceed with Creating a new Documentation Plugin in that case.
Creating a new Documentation Plugin
Create a new plugin project:
-
Select New & Project & Plug-in Project
-
Click Next
-
Enter a project name, e.g. org.eclipse.stardust.docs.mydocs
-
In the Location field enter the location of your checked out stardust/documentation followed by the plugin name.
-
Click Next
-
In the Content dialog click Next
-
Select the Create a plug-in using one of the templates option
-
In the Available templates section select Plug-in with sample help content
-
Click Next
-
In the Sample Help Table of Contents dialog, select Primary and add an appropriate label.
Editing the Documentation Plugin
Now you see the new plugin 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 plugin 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
Linking a Documentation Plugin to Stardust Documentation
Adding a Link to the main Documentation Plugin
The main documentation plugin 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 plugin 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"
Including the Documentation Plugin in Documentation Features
Style Guide
Please refer to the Eclipse Doc Style Guide for a general guide on Eclipse documentation styling.
To provide our Stardust documentation style, copy the following to the html folder of your documentation plugin: media:styles styles
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.