Convert documentation to AsciiDoc, publish to GitHub Pages or eclipse.dev

[kriegaex]

Why?

• Easier to read and maintain than DocBook XML and HTML
• GitHub automatically displays it correctly
• More formatting and structuring options than Markdown
• Get rid of ancient DocBook dependencies in lib module

How?

• [x] Use CLI tool like Pandoc for initial conversion
• [x] Manually fix the rest
• [x] Add Maven build step for Asciidoc generation
• [x] Update Maven build step for integrating generated docs incl. javadocs into installer package
• [x] Get rid of DocBook build steps and dependencies
• [x] Decide where and how to publish
  • Eclipse AspectJ project page
  • :+1: Uses existing infrastructure (Eclipse server, website repo)
  • :+1: Seamless integration into Eclipse project page
  • :+1: Least disruptive change for users
  • GitHub Pages
  • :+1: Independent of Eclipse infrastructure and PHP-driven templates like Hugo Solstice theme
  • :-1: No seamless integration into Eclipse project page
  • :-1: No Eclipse infra team support
  • :+1: Docs are just a GH branch or separate repo
  • :-1: If docs are a branch and we want per-version docs, the repo size might grow quickly
  • No docs website at all, rely on GitHub asciidoc and/or markdown formatting. Provide links to the most important docs sources on the main read-me and let users browse directly from the repository.
  • :+1: No extra build and post-build manual steps
  • :+1: Browsing docs by branch or tag after the cut-over comes for free
  • :-1: Asciidoc includes do not work on GH, i.e. one-page versions of multi-page docs are impossible
  • :-1: Publishing docs in other formats like PDF would require extra GH pages or Eclipse storage space, because we do not want to commit them to the Git repository
• [x] Perform initial upload manually
• [ ] After publication, arrange with Eclipse infra team to create redirects for either variant, because even if we stick with the existing Eclipse server and only one (current) docs version published, URLs and intra-document HTML anchors will change
• [x] #276 (optional)
• [x] Publish via GitHub action on master merge or release tag (optional)
• [x] Integrate Javadoc into publishing process (optional)

[kriegaex]

@aclement, I have been working on and off on this during the last 4 weeks. I am not done yet and have no HTML generation step for it yet, but first wanted to focus on making the documents readable and navigable directly from the GitHub repo. I would appreciate some feedback. Here are some entry points:

• https://github.com/kriegaex/org.aspectj/blob/docs-to-asciidoc/docs/dist/doc/index.adoc \ (still several links to fix, but click on the release notes per version)
• https://github.com/kriegaex/org.aspectj/blob/docs-to-asciidoc/docs/adk15ProgGuideDB/adk15notebook.adoc \ Locally, I use include statements in order to get it rendered as a single document with a table of contents, but GitHub does not do that automatically, they block it and convert the includes into an ugly list of naked document links.
• https://github.com/kriegaex/org.aspectj/blob/docs-to-asciidoc/docs/devGuideDB/devguide.adoc \ Same limitation for includes applies.
• https://github.com/kriegaex/org.aspectj/blob/docs-to-asciidoc/docs/pdGuideDB/pdguide.adoc \ Same limitation for includes applies.
• https://github.com/kriegaex/org.aspectj/blob/docs-to-asciidoc/docs/progGuideDB/progguide.adoc \ Same limitation for includes applies.
• https://github.com/kriegaex/org.aspectj/blob/docs-to-asciidoc/docs/developer/index.adoc \ Same limitation for includes applies.

There are some more documents I converted, but this should give you a good first impression of what the AsciiDoc looks like (no apecific styling applied, all using defaults).

Ideally, the links should just work on GitHub, so we have a living documentation. We can of course add an AsciiDoctor conversion step and regularly upload generated HTMLs for a static documentation website, similar to what we have now.

P.S.: Sample code in the documentation (e.g. Java, AspectJ, XML) has syntax highlighting now.

[edyda99]

Hi, is it possible to split this issue into multiple sub-issues and label them as ideal for contribution, new people (like me) will get the opportunity to contribute and will get to know more about this amazing library?

[kriegaex]

Hi, is it possible to split this issue into multiple sub-issues

Actually, I am 95% done and simply deprioritised this issue in favour of others. Part of it was laziness, too, I admit to that. One of these days, I should kick my own ass and finish it.

[kriegaex]

Reopening, because even though the PR as such is done and merged, the website still has not been updated. Open questions for how exactly to do it, see Eclipse help desk issue 4123.

[kriegaex]

For now, I made the decision to publish on https://eclipse.dev/aspectj/, but cannot do anything there at the moment, because the website seems to have problems, see GitLab issue 4287.

[kriegaex]

We reached the next milestone: I updated the old PHP website, at least as much as necessary for now. For example:

• Removed old news from main index page
• Restructured downloads page
• Updated link to Git repository
• FAQ and docs now point to asciidoc-generated content (old content is still around, because the redirects are still an open to-do)

[kriegaex]

I created a URL mapping table from old to new documentation URLs and opened helpdesk issue https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/4304.

[kriegaex]

The 3 optional steps will not be done as part of this issue. I want to close it after the URL mapping and tend to other issues after expending considerable effort on this one.