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
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
From Wikipedia : DocBook is a semanticmarkup 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.
Customisable pdf and html export, with templates, possibilities to have a header, footer, first page, etc.
Linked to JIRA
No automatic generation of documents
Other tools & technologies considered
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.
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.