Goals
The goal of "Online Help" is to provide documentation for the toolbox developers :
- Modules developers should find information on how to develop new modules and access APIs in java native languages and other supported languages.
- Toolbox developer should find information about the toolbox design to understand the architecture of the software and facilitate understanding of its internal working mechanisms.
Requirements
| # | Title | Importance |
|---|
| 1 | It must provide a structured online help for developers | Must Have |
| 2 | It must be exportable to PDF and DOC format | Must Have |
| 3 | It should have index and search | Should Have |
| 4 | It should be integrated to the Sentinel ESA website | Should Have |
| 5 | It should make it be easy to add new content without specific knowledge of the technology chosen | Should Have |
| 6 | It might be generated automatically (html, pdf and doc) | Might Have |
| 7 | It might be exportable to SDD for S1, S2 and S3 toolboxes | Might Have |
| 8 | It might have chapters linked to requirements and issues in JIRA | Might Have |
Sphinx
http://sphinx-doc.org/
From the web page:
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well. Of course, this site is also created from reStructuredText sources using Sphinx! The following features should be highlighted:
- Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
- Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
- Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
- Automatic indices: general index as well as a language-specific module indices
- Code handling: automatic highlighting using the Pygments highlighter
- Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Pros:
- Standard
- Widely used
- Looks good
Cons:
- Only Python and C++ supported at the moment, a project exists for code in Java (https://bronto.github.io/javasphinx/#) but it still is very Python oriented, mainly for Python projects using Java.
- No direct export to word
- No link with requirements and issues
DocBook
From Wikipedia : DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation.
As a semantic language, DocBook enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages, Web help[2] and HTML Help, without requiring users to make any changes to the source.
Pros:
- Standard
- XML format, with many editors and plugins for NetBeans, IntelliJ, etc.
- Xslt processors for MS Word, html, pdf, etc.
- Search with webhelp
- Web pages and docs can be automatically generated
Cons:
- New content added by developers only: adding new content needs a specific editor or an XML editor, does not seem “user friendly”.
- Conversion from existing HTML pages not straightforward
- Lots of work foreseen to have a nice output
- No link with requirements and issues
Wiki
Many wiki exist, with pdf and word export plugins, like XWiki (plugins to export to word, pdf export directly supported) or DocuWiki (pdf export supported via plugin, no MS Work export).
Pros:
- Easy to edit content
- Easy setup
- Possible to enable user comments
- Might be available on ESA Sentinel Website
Cons
- If not available on ESA Sentinel Website (or no proper export)
- New website will have to be setup and maintained
- Might not integrate on ESA Sentinel Website
- Usually not easy to generate a nice structured document
- no automatic generation
JIRA
Confluence JIRA gives the possibility to create technical documentation, with customisable PDF, XML and HTML export: https://confluence.atlassian.com/display/DOC/Developing+Technical+Documentation+on+Confluence+Wiki
Pros:
- Create link with the requirements and issues
- Customisable pdf and html export, with templates, possibilities to have a header, footer, first page, etc.
Cons:
- Linked to JIRA
- No automatic generation of documents
- Direct creation of web pages on the ESA Sentinel website, if it is possible and export is possible
- JasperReport: Export to html, pdf and doc but mainly for reporting (graphics, tables, etc.)
- Eclipse help: no direct export to pdf or word, and is built for applications, not online help
- CMS like drupal have some export plugins. This however would require maintaining an other website, similar to Wikis.
- Export from Office documents is possible, but the html export has limited functionalities (search, etc.) and generated html is not “clean” or can be hard to configure.
Conclusion
From the above analysis there are 3 main options:
- Direct creation of web pages on the ESA Sentinel website, if customisable export to pdf and doc is possible. This would be the simplest solution, remains to see what is possible on the STEP website and how (and by whom) it can be updated (Wiki…).
- DocBook is a standard and enables export to all wanted format but it will be time consuming to have a nice result, it is not “user friendly” and there will be no direct links with requirements in JIRA.
- JIRA enables to create technical documentation. This documentation could be exported to html and pdf for STEP website. This has the advantage of having all documentation in one place and of linking requirements, specifications, design and issues. Furthermore it has nice export capabilities that could be extended.