Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 0.3-incubating
    • Component/s: None
    • Labels:
      None

      Description

      We need to decide on a documentation format for the DeltaSpike documentation. Requirements are:

      1. Kept in the VCS with the DeltaSpike codebase
      2. Buildable with Maven
      3. Can generate multiple formats, including HTML and PDF

      Currently the "industry standard" is DocBook, however there may be other alternatives which are more suitable. Suggestions welcome here.

        Activity

        Hide
        Gerhard Petracek added a comment -

        apache cms is used currently

        Show
        Gerhard Petracek added a comment - apache cms is used currently
        Hide
        Jason Porter added a comment -

        Another tool has recently come to my attention: ASCIIDOC (www.methods.co.nz/asciidoc/). It's quite easy to use and understand (www.methods.co.nz/asciidoc/userguide.html). It also has the advantage of outputting docbook, epub, pdf, html, manpages, etc. It's also written in python. Version 8.6.7 works on jython. If we wanted to use it from Maven, we'd need to write a plugin, but so far using it has been very enjoyable and really not that much harder to pickup than markdown. Just another option to consider.

        Show
        Jason Porter added a comment - Another tool has recently come to my attention: ASCIIDOC (www.methods.co.nz/asciidoc/). It's quite easy to use and understand (www.methods.co.nz/asciidoc/userguide.html). It also has the advantage of outputting docbook, epub, pdf, html, manpages, etc. It's also written in python. Version 8.6.7 works on jython. If we wanted to use it from Maven, we'd need to write a plugin, but so far using it has been very enjoyable and really not that much harder to pickup than markdown. Just another option to consider.
        Hide
        Jason Porter added a comment -

        We're looking at Sphinx: http://sphinx.pocoo.org/. It's the standard in the Python community. John is taking a look at it as well.

        Show
        Jason Porter added a comment - We're looking at Sphinx: http://sphinx.pocoo.org/ . It's the standard in the Python community. John is taking a look at it as well.

          People

          • Assignee:
            Jason Porter
            Reporter:
            Shane Bryzak
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development