Jump to: navigation, search

Papyrus Developer Guide/Writing Documentation

How to - Write documentation for Papyrus

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

Papyrus-Help-plugin.png

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.