Jackrabbit Oak
  1. Jackrabbit Oak
  2. OAK-301 Document Oak
  3. OAK-936

Incorporate Oak documentation into the Oak website

    Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 0.9
    • Component/s: doc
    • Labels:
      None

      Description

      We should incorporate the Oak documentation into the Oak web site .

      Optimally we make this part of our CI and release infrastructure. Each CI build would deploy the latest snapshot build of oak-doc to http://jackrabbit.apache.org/oak/docs/nightly. Each release would deploy a build of oak-doc to http://jackrabbit.apache.org/oak/releases/oak-doc-X.Y

        Activity

        Michael Dürig created issue -
        Hide
        Jukka Zitting added a comment -

        I'm not too excited about the CI build approach, given how the ASF web infrastructure works. I've tried setting up and maintaining such site builds on a few projects, but it always ends up being a more trouble than it's worth given the various security constraints (site must be in svn, but one shouldn't store svn credentials on a CI server, etc.).

        Instead I'd rather just use static files, possibly with something like strapdown.js for rendering. That way a documentation update can be deployed simply by committing the changes.

        Show
        Jukka Zitting added a comment - I'm not too excited about the CI build approach, given how the ASF web infrastructure works. I've tried setting up and maintaining such site builds on a few projects, but it always ends up being a more trouble than it's worth given the various security constraints (site must be in svn, but one shouldn't store svn credentials on a CI server, etc.). Instead I'd rather just use static files, possibly with something like strapdown.js for rendering. That way a documentation update can be deployed simply by committing the changes.
        Hide
        Michael Dürig added a comment -

        I'm not too excited about the CI build approach

        Scrap that the CI idea.

        The approach I'm trying out uses the site plugin to build html files from the markdown files in oak-doc and then commit them to our web site. Every committer should be able to use that without additional fiddling with the credentials. I'll follow up on OAK-301.

        Show
        Michael Dürig added a comment - I'm not too excited about the CI build approach Scrap that the CI idea. The approach I'm trying out uses the site plugin to build html files from the markdown files in oak-doc and then commit them to our web site. Every committer should be able to use that without additional fiddling with the credentials. I'll follow up on OAK-301 .
        Hide
        Thomas Mueller added a comment -

        The mvn site approach is fine with me. Just a few thought about alternatives:

        • strapdown.js: it's an interesting idea, however I'm not quite sure if the claim they make about "Search-engine friendly" is really true... Does anybody know the details?
        • TiddlyWiki - each document would be its on wiki.
        • Edit the raw html. This is what I usually do. It avoids having to learn another markup language (assuming you know HTML). There are a few disadvantages, but in my view they are not major (lack of templating; HTML is a bit verbose).
        Show
        Thomas Mueller added a comment - The mvn site approach is fine with me. Just a few thought about alternatives: strapdown.js: it's an interesting idea, however I'm not quite sure if the claim they make about "Search-engine friendly" is really true... Does anybody know the details? TiddlyWiki - each document would be its on wiki. Edit the raw html. This is what I usually do. It avoids having to learn another markup language (assuming you know HTML). There are a few disadvantages, but in my view they are not major (lack of templating; HTML is a bit verbose).
        Hide
        Michael Dürig added a comment -

        The initial bits are in place. Let's follow up with separate issues to refine or change this to another approach if it turns out to be necessary.

        Show
        Michael Dürig added a comment - The initial bits are in place. Let's follow up with separate issues to refine or change this to another approach if it turns out to be necessary.
        Michael Dürig made changes -
        Field Original Value New Value
        Status Open [ 1 ] Resolved [ 5 ]
        Assignee Michael Dürig [ mduerig ]
        Resolution Fixed [ 1 ]
        Alex Parvulescu made changes -
        Fix Version/s 0.9 [ 12324541 ]
        Hide
        Alex Parvulescu added a comment -

        Bulk close for the 0.9 release

        Show
        Alex Parvulescu added a comment - Bulk close for the 0.9 release
        Alex Parvulescu made changes -
        Status Resolved [ 5 ] Closed [ 6 ]

          People

          • Assignee:
            Michael Dürig
            Reporter:
            Michael Dürig
          • Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development