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.
Difference between revisions of "Papyrus/Papyrus Developer Guide/Writing Documentation"
(→Creating the first version of the documentation) |
m |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == How to - Write documentation for Papyrus == | + | == 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 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 === | + | Documentation should follow these recommendations [https://wiki.eclipse.org/Eclipse_Doc_Style_Guide Eclipse Doc Style] |
| − | The document | + | |
| − | The following page can be used as example: [http://wiki.eclipse.org/MDT/Papyrus/UserGuide/Search User Guide / Search] | + | === 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: [http://wiki.eclipse.org/MDT/Papyrus/UserGuide/Search 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]] | ||
| + | |||
| + | [[Image: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 : | ||
| + | |||
| + | <source lang="xml"> | ||
| + | <?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> | ||
| + | </source> | ||
| + | |||
| + | '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 | ||
| + | |||
| + | <source lang="xml"> | ||
| + | <?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> | ||
| + | </source> | ||
| + | |||
| + | 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. | ||
| + | |||
| + | [[Category:Papyrus]] | ||
Revision as of 09:51, 7 May 2014
Contents
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
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.