Enhancement #779
Evaluate if Sphinx is a Basis for Better Concept, Installation and Tool Usage Documentation
| Status: | Resolved | Start date: | 12/21/2011 | |
|---|---|---|---|---|
| Priority: | Normal | Due date: | ||
| Assignee: | - | % Done: | 100% | |
| Category: | Documentation | |||
| Target version: | - |
Description
Should a Sphinx -based manual be added to RSB?
Goals:- The manual shall not replace the reference documentation (API docs)
- The manual should be cross-referenced with API docs where appropriate
- The manual should provide versioned documentation of
- high-level concepts
- installation aspects
- tool usage
- The manual should contain tutorials?
- There is an experimental manual folder (source:trunk/manual) in the top-level of the source tree. Contents:
- Partial introduction to concepts
- Tutorial skeleton
- man-page-like documentation of tools
- Possible outputs
- HTML manual
- PDF manual
- man-pages for tools
We are quite confident that such a manual is useful.
Related issues
History
#1 Updated by J. Moringen over 12 years ago
- Description updated (diff)
- Status changed from New to Feedback
- % Done changed from 0 to 20
#2 Updated by J. Moringen over 12 years ago
- % Done changed from 20 to 60
Sphinx seems suitable. However, before we can do any serious documentation, the following decisions have to be made
- Scope (e.g. one huge manual for the entire RSB ecosystem? separate manuals for sub-projects?)
- Style
- Macro level (e.g. general introduction? Man-page-like? Tutorials? combinations of these?)
- Micro (e.g. "documentation conventions")
- Structure
- Can we come up with generic skeleton structure for projects (which would be applicable to e.g. Redmine sub-projects)?
- How can overarching (spanning multiple projects like RSBag and rsb-gstreamer) topics be covered?
Maybe this requires additional topic-centric manuals like "Common use-cases for data recoding, visualization and evaluation"
- Deployment
- One possibility: dedicated top-level documentation URI on a CoR-Lab server for all projects
- Another possibility: www.readthedocs.org
- Integration
- Epydoc
- Doxygen
- JavaDoc
- cl-docutils
#3 Updated by J. Moringen over 12 years ago
- Description updated (diff)
#4 Updated by J. Wienke over 12 years ago
To my mind we can resolve this issue. We have so much stuff working with sphinx now that this is not directly an evaluation phase anymore.
#5 Updated by S. Wrede over 12 years ago
- Status changed from Feedback to Resolved
- % Done changed from 60 to 100
I agree. It looks as this was a really good proposal by Dimitri.