How to generate the Eclipse Help from markdown pages in GitHub wiki

msohn commented 9 months ago

Description

After migrating JGit and EGit repos to GerritHub and their wikis from wikimedia to GitHub wiki we need to figure out how to generate Eclipse help pages from GFM markdown pages in the GitHub wikis. So far we used Mylyn to convert from wikimedia content to Eclipse help which is shipped in the bundle eclipse.egit.doc.

Motivation

We need to continue providing JGit and EGit documentation as Eclipse help pages

Alternatives considered

No response

Additional context

Looks like DITA Open Toolkit [1] supports import from GFM markdown and output to Eclipse help.

[1]

DITA Open Toolkit: https://www.dita-ot.org/
markdown input: https://www.dita-ot.org/dev/topics/markdown-input
eclipsehelp output: https://www.dita-ot.org/dev/topics/dita2eclipsehelp.html

Bananeweizen commented 9 months ago

How exactly was the migration from mediawiki to github wiki done (shame on me for not knowing it from the mailing list)? I'm mainly asking because it would be an alternative to not use github wiki pages, but rather some other markdown and to generate help from that. E.g. at work we use AsciiDoc for all our documents and we generate HTML from that via the standard AsciiDoc maven plugin. The only missing puzzle piece is then to also generate a TOC for Eclipse, and there we use the (no longer maintained) https://github.com/jmini/geneclipsetoc.

I'm meanwhile a big fan of AsciiDoc for all kinds of documentation, because it has a good compromise between simple syntax and allowing even very complex layouting. A prominent example for usage of AsciiDoc around Eclipse might be the Eclipse UI guideline at https://github.com/eclipse-platform/ui-best-practices (code) and https://eclipse-platform.github.io/ui-best-practices/ (html).

msohn commented 9 months ago

I described the steps I used to migrate the wiki in the README of https://github.com/msohn/EclipseWikiCrawler

Bananeweizen commented 9 months ago

I've only touched DITA very lightly (one of the products at work has built-in DITA document support), so I can't really judge that alternative. Also I haven't heard much of it in my day-to-day documentation usage, so I'm not sure how much community is behind it. At the same time I see a rather growing AsciiDoc community and usage. The separate help output goal however is a positive point for DITA.

The core maintainer of AsciiDoctor has written a markdown to AsciiDoc converter, which has excellent reviews for the quality of the AsciiDoc produced: https://github.com/asciidoctor/kramdown-asciidoc. For me everything coming after that converter would be "known territory" where I know it works well. The AsciiDoc conversion approach would have 2 further flavors:

Converting just one time, and storing the AsciiDoc instead of having the wiki.
Converting the wiki input each time.

I'm probably biased, but the one-time conversion is more appealing to me:

It avoids a bigger tech stack including Ruby in the build. The AsciiDoc conversion can all be done with Maven plugins as part of the normal build.
It can produce a help with separate pages per topic and at the same time an online hosted documentation consisting of a single HTML page. Check the https://eclipse-platform.github.io/ui-best-practices/ again, it's a single document. That simplifies external linking, indexing etc. a lot.
To simplify the contribution cycle for editors, we can have the typical "Edit on GitHub" overlay in a corner, and we can run the documentation generation as action after each commit to master.

I can implement the AsciiDoc conversion, both for the help and online variants.

That all said, it would surely be good to hear some other opinions to get a better picture.

msohn commented 9 months ago

I am ok to switch to the more powerful AsciiDoc but have no time to work on this conversion. I guess GitHub can also render AsciiDoc on the fly.

If you have time and experience to do this I can support you with reviews.

I'd like to keep this outside of the source code repos since the contained images bloat repo size. We could put it into the website repo or create a new repo for documentation.

Ideally we don't check in the documentation converted to eclipse-help but do the conversion only in the build. I think if we go this path then this should be done in a separate Maven profile which we can skip during development builds to keep build times short.

eclipse-egit / egit