Difference between revisions of "Papyrus/Papyrus Developer Guide/Writing Documentation"

Revision as of 09:17, 20 March 2015

How to - Write documentation for Papyrus for Mars

Context

Documentation should be accessible online and in the documentation embedded in Eclipse platform. Both places should be coherent, so a common format is used. Documentation should follow these recommendations Eclipse Doc Style The official version is the one attached to the git repository.

All documentations are localized inside several plugins at org.eclipse.papyrus/plugins/doc.

Step 1: create your own documentation plugin

Step 2: attached it to the build process

Step 3: attached it to the feature doc

Step 4: test it

You could execute an Eclipse RCP platform from your initial platform: your documentation should be lived in the help menu. You could also execute a full local release of Papyrus by running a mvn clean install -f releng/top-main-pom.xml

How to - Write documentation for Papyrus for Luna version and previous versions

Documentation should be accessible online and in the documentation embedded in Eclipse platform. Both places should be coherent, so a common format is used.

Documentation should follow these recommendations Eclipse Doc Style

Writing the first version of the documentation

The document is first created as a page in the eclipse wiki. A rich editor is accessible from wiki pages, so a pretty documentation can be writtten. The following page can be used as example: User Guide / Search.

Importing the documentation in a plugin

• Once the help page is written on Eclipse wiki, copy the content of the page from the wiki editor (simple one, not the rich editor).
• Paste the content in a document called yourname.mediawiki in an existing documentation plugin or in a new one.

The set of Mylyn wikitext plugins should be installed: Mylyn/WikiText

Exporting as embedded documentation

• On the mediawiki file, select in the context menu the "WikiText" => "Generate Eclipse documentation" action. It will generate a html file and a table of content (TOC) file.

• Create a new TOC file that will reference the generated TOC file

Content of the search-main-toc.xml file :

<?xml version='1.0' encoding='utf-8' ?>
<toc label="Search" link_to="../org.eclipse.papyrus.infra.doc/toc.xml#PapyrusDocUser">
   <topic href="resource/search.html" label="Search in Models">
      <link toc="resource/search-toc.xml"/>
      <anchor id="searchInModel"/>
   </topic>	
</toc>

'link_to' add the contribution to the PapyrusDocUser anchor (defined in the main papyrus documentation plugin)
warning: paths are related to the root of the plugin
the generated TOC is referenced by the hand-written one. An anchor is also added here, so the search documentation can be extended by another contribution.

• Add all images embedded in the documentation in the same folder as the mediawiki and all generated files.

• Do not forget to add all files (the folder resource in the example) to the build.properties file.

• Reference the TOCs in the extensions of the plugin

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension point="org.eclipse.help.toc">
      <toc file="resource/search-main-toc.xml" primary="false"/>
      <toc file="resource/search-toc.xml" primary="false"/>
   </extension>
</plugin>

Documentation plugin is ready to be tested and shipped with Papyrus! At any moment, it is possible to modify the wiki page, copy/paste the content in the mediawiki file, and regenerate the eclipse documentation.

The generated content is not modified, so there is no problem to override existing generated files.