[
https://issues.apache.org/jira/browse/ARTEMIS-4383?focusedWorklogId=874120&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-874120
]
ASF GitHub Bot logged work on ARTEMIS-4383:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 01/Aug/23 20:29
Start Date: 01/Aug/23 20:29
Worklog Time Spent: 10m
Work Description: jbertram opened a new pull request, #4573:
URL: https://github.com/apache/activemq-artemis/pull/4573
Markdown, which is currently used for user-facing documentation, is good for
a lot of things. However, it's not great for the kind of complex documentation
we have and our need to produce both multi-page HTML and single-page PDF output
via Maven.
Markdown lacks features which would make the documentation easier to read,
easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Hokit is
written in TypeScript and is installed via NPM. Calibre is a native tool so it
must be installed via an OS-specific package manager. All this complexity makes
building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features for
presentation and navigation not to mention Java-based Maven tooling to generate
both HTML and PDF. Migrating will improve both the appearance of the
documentation as well as the processes to generate and upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which will have
PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per line
and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
Issue Time Tracking
-------------------
Worklog Id: (was: 874120)
Remaining Estimate: 0h
Time Spent: 10m
> Migrate user docs to AsciiDoc
> -----------------------------
>
> Key: ARTEMIS-4383
> URL: https://issues.apache.org/jira/browse/ARTEMIS-4383
> Project: ActiveMQ Artemis
> Issue Type: Task
> Reporter: Justin Bertram
> Assignee: Justin Bertram
> Priority: Major
> Time Spent: 10m
> Remaining Estimate: 0h
>
> Markdown, which is currently used for user-facing documentation, is good for
> a lot of things. However, it's not great for the kind of complex
> documentation we have and our need to produce both multi-page HTML and
> single-page PDF output via Maven.
> Markdown lacks features which would make the documentation easier to read,
> easier to navigate, and just look better overall.
> The current tool-chain uses [honkit|https://github.com/honkit/honkit] and a
> tool called [Calibre|https://manual.calibre-ebook.com/]. Hokit is written in
> TypeScript and is installed via NPM. Calibre is a _native_ tool so it must be
> installed via an OS-specific package manager. All this complexity makes
> building, releasing, uploading, etc. a pain.
> AsciiDoc is relatively simple like Markdown, but it has more features for
> presentation and navigation not to mention Java-based Maven tooling to
> generate both HTML and PDF. Migrating will improve both the appearance of the
> documentation as well as the processes to generate and upload it.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
