Skip to main content
Jump to: navigation, search

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

m (Add Papyrus category)
m
Line 2: Line 2:
  
 
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 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 [https://wiki.eclipse.org/Eclipse_Doc_Style_Guide Eclipse Doc Style]
  
 
=== Writing the first version of the documentation  ===
 
=== Writing the first version of the documentation  ===
Line 38: Line 40:
 
  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.
 
  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.
+
*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.
 
*Do not forget to add all files (the folder resource in the example) to the build.properties file.

Revision as of 09:51, 7 May 2014

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.

Back to the top