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

Papyrus/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.

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

Back to the top