[
https://issues.apache.org/jira/browse/ARTEMIS-4383?focusedWorklogId=874241&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-874241
]
ASF GitHub Bot logged work on ARTEMIS-4383:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 02/Aug/23 10:54
Start Date: 02/Aug/23 10:54
Worklog Time Spent: 10m
Work Description: gemmellr commented on code in PR #4573:
URL: https://github.com/apache/activemq-artemis/pull/4573#discussion_r1281596556
##########
RELEASING.md:
##########
@@ -315,26 +315,15 @@ Once the mirrors are up-to-date then update the following:
with the HTML from the bottom of the release notes url you sent out with
your VOTE email (appending `&styleName=Text`).
2. Copy `src/_artemis_releases/artemis-<old-version>-release.md` to
`src/_artemis_releases/artemis-<new-version>-release.md`. Update the versions
and dates.
3. Update the _artemis_ list within the `src/_data/current_releases.yml` file
if needed.
-4. Copy `src/components/artemis/documentation/latest` to
`src/components/artemis/documentation/<old-version>`.
+4. Rename `src/components/artemis/documentation/latest` to
`src/components/artemis/documentation/<old-version>`.
5. Build the `artemis-website` module from the new-version release sources
with `mvn clean package -Prelease`.
-6. Create `src/components/artemis/documentation/latest` and copy these files
into it:
- 1. the contents of user-manual from
`apache-artemis-<new-version>/web/user-manual`
- 2. book.pdf version of user-manual (generated from the new-version sources
at `artemis-website/target/scratch/user-manual/` with the command `gitbook pdf`)
- 3. book.epub version of user-manual (generated from the new-version
sources at `artemis-website/target/scratch/user-manual/` with the command
`gitbook epub`)
- 4. book.mobi version of user-manual (generated from the new-version
sources at `artemis-website/target/scratch/user-manual/` with the command
`gitbook mobi`)
-7. Create `src/components/artemis/documentation/hacking-guide` and copy these
files into it:
- 1. the contents of hacking-guide from
`apache-artemis-<new-version>/web/hacking-guide`
- 2. book.pdf version of hacking-guide (generated with `gitbook pdf`)
-8. Copy `src/components/artemis/documentation/javadocs/javadoc-latest` to
`src/components/artemis/documentation/javadocs/javadoc-<old-version>`.
-9. Create `src/components/artemis/documentation/javadocs/javadoc-latest` and
copy the contents of `apache-artemis-<new-version>/web/api` into it.
+6. Create `src/components/artemis/documentation/latest` and copy into it the
contents of `target/user-manual` from the `artemis-website` module which you
just built.
+7. Rename `src/components/artemis/documentation/javadocs/javadoc-latest` to
`src/components/artemis/documentation/javadocs/javadoc-<old-version>`.
+8. Create `src/components/artemis/documentation/javadocs/javadoc-latest` and
copy into it the contents of `target/apidocs` from the `artemis-website` module
which you just built.
Review Comment:
We no longer do this quite the same way described, as we discussed keeping
only the latest Javadoc (instead of the proposals to remove it entirely, or
just link to an archive), but must have not updated the instructions to reflect
it. Needs tweaked accordingly (I'll suggest her rather than creating a conflict
you need to resolve), e.g:
```suggestion
7. Delete `src/components/artemis/documentation/javadocs/javadoc-latest` to
clear the old/existing content (in case any files are being moved/removed by
the new version).
8. Create `src/components/artemis/documentation/javadocs/javadoc-latest`
again and copy into it the contents of `target/apidocs` from the
`artemis-website` module which you just built.
```
##########
.gitignore:
##########
@@ -31,12 +31,9 @@
artemis-native/src/main/c/org_apache_activemq_artemis_jlibaio_LibaioContext.h
# generated by shade
**/dependency-reduced-pom.xml
-# gitbook output
-docs/user-manual/en/_book
-docs/hacking-guide/en/_book
-
# overlay outpit
**/overlays/**/*
-# result of gitbook pdf under docs
-docs/user-manual/en/book.pdf
+# generated by the `artemis-website` build
+/docs/user-manual/client-classpath-jakarta.adoc
+/docs/user-manual/client-classpath-jms.adoc
Review Comment:
We shouldn't really be generating stuff inside the source/non-target tree to
begin with, especially not into _other_ modules trees. It will also be left
behind and put in the source release archive unless explicitly excluded \[1\].
The existing stuff made a scratch copy of the docs in the artemis-website
target dir to work on, and do some filtering around placeholders for versions
etc. We could probably just continue to do that even if we dont need the
filtering anymore.
\[1\] On this exclusions point, there are some similar 'creating stuff
outside target' related exclusions for the old docs build stuff that can
presumably be removed along with it, e.g:
[here](https://github.com/apache/activemq-artemis/blob/2.30.0/artemis-distribution/src/main/assembly/source-assembly.xml#L55-L57)
and
[here](https://github.com/apache/activemq-artemis/blob/2.30.0/artemis-distribution/src/main/assembly/source-assembly.xml#L148-L149).
##########
artemis-website/pom.xml:
##########
@@ -29,24 +29,20 @@
<properties>
<activemq.basedir>${project.basedir}/..</activemq.basedir>
- <webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
-
<src-dir-user-manual>${basedir}/../docs/user-manual/en</src-dir-user-manual>
-
<scratch-dir-user-manual>${basedir}/target/scratch/user-manual</scratch-dir-user-manual>
-
<webapp-outdir-user-manual>${basedir}/target/classes/user-manual</webapp-outdir-user-manual>
-
<webapp-outdir-hacking-guide>${basedir}/target/classes/hacking-guide</webapp-outdir-hacking-guide>
-
<webapp-outdir-migration-guide>${basedir}/target/classes/migration-guide</webapp-outdir-migration-guide>
-
- <frontend-maven-plugin-version>1.12.1</frontend-maven-plugin-version>
- <nodeVersion>v18.15.0</nodeVersion>
- <npmVersion>9.6.2</npmVersion>
+
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>2.3.9</asciidoctorj.pdf.version>
Review Comment:
Lets stick these in the root pom this time, along with everything else
similar.
##########
artemis-website/pom.xml:
##########
@@ -29,24 +29,20 @@
<properties>
<activemq.basedir>${project.basedir}/..</activemq.basedir>
- <webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
-
<src-dir-user-manual>${basedir}/../docs/user-manual/en</src-dir-user-manual>
-
<scratch-dir-user-manual>${basedir}/target/scratch/user-manual</scratch-dir-user-manual>
-
<webapp-outdir-user-manual>${basedir}/target/classes/user-manual</webapp-outdir-user-manual>
-
<webapp-outdir-hacking-guide>${basedir}/target/classes/hacking-guide</webapp-outdir-hacking-guide>
-
<webapp-outdir-migration-guide>${basedir}/target/classes/migration-guide</webapp-outdir-migration-guide>
-
- <frontend-maven-plugin-version>1.12.1</frontend-maven-plugin-version>
- <nodeVersion>v18.15.0</nodeVersion>
- <npmVersion>9.6.2</npmVersion>
+
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>2.3.9</asciidoctorj.pdf.version>
<skipWebsiteDocGeneration>false</skipWebsiteDocGeneration>
<skipWebsiteJavadocGeneration>false</skipWebsiteJavadocGeneration>
+ <skipWebsitePdfGeneration>false</skipWebsitePdfGeneration>
Review Comment:
I'd be inclined to default this to the existing skipWebsiteDocGeneration
property. Otherwise, anyone who already knows and enables
skipWebsiteDocGeneration currently, will now find it still then goes and builds
the documentation PDF now.
##########
docs/user-manual/_diagrams/client-classpath-jms.adoc:
##########
@@ -1 +1 @@
-This file will be generated/replaced in compile time by artemis-website
\ No newline at end of file
+This file will be generated/replaced in compile time by artemis-website
Review Comment:
Ditto
##########
artemis-website/pom.xml:
##########
@@ -29,24 +29,20 @@
<properties>
<activemq.basedir>${project.basedir}/..</activemq.basedir>
- <webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
-
<src-dir-user-manual>${basedir}/../docs/user-manual/en</src-dir-user-manual>
-
<scratch-dir-user-manual>${basedir}/target/scratch/user-manual</scratch-dir-user-manual>
-
<webapp-outdir-user-manual>${basedir}/target/classes/user-manual</webapp-outdir-user-manual>
-
<webapp-outdir-hacking-guide>${basedir}/target/classes/hacking-guide</webapp-outdir-hacking-guide>
-
<webapp-outdir-migration-guide>${basedir}/target/classes/migration-guide</webapp-outdir-migration-guide>
-
- <frontend-maven-plugin-version>1.12.1</frontend-maven-plugin-version>
- <nodeVersion>v18.15.0</nodeVersion>
- <npmVersion>9.6.2</npmVersion>
+
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>2.3.9</asciidoctorj.pdf.version>
<skipWebsiteDocGeneration>false</skipWebsiteDocGeneration>
<skipWebsiteJavadocGeneration>false</skipWebsiteJavadocGeneration>
+ <skipWebsitePdfGeneration>false</skipWebsitePdfGeneration>
+
+ <!
Issue Time Tracking
-------------------
Worklog Id: (was: 874241)
Time Spent: 0.5h (was: 20m)
> 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: 0.5h
> 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)
