Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Incorporating Jamal macro into the documentation #1229

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

verhas
Copy link

@verhas verhas commented Jun 29, 2023

Documentation maintenance enhancement adding Jamal to the documentation toolset

  • Bug fix
  • New non-breaking feature
  • New breaking feature
  • Documentation update
  • Build improvement

Description

Goal

Adding this change to the build process, the documentation will automatically fetch and use the latest release.
Later the tool use can be gradually extended to reduce documentation and code redundancy, automatically pulling information from the documented source code into the documentation.

The pull request

  • adds Jamal as a test dependency to the toolset and
  • contains a test that converts the new README.adoc.jam file into README.adoc.
  • It also moved the content of the README.adoc to README.adoc.jam and extended it with macros to fetch the versions automatically when the documentation is processed while editing in IntelliJ/AsciidocFX or during the build.

An alternative way could be to write some specific test that updates the documentation, but Jamal does it, and it is a powerful framework for the very purpose. I do not know any professional alternative. It is also possible to keep editing the pure Asciidoc without macros and invest the manual effort to keep the version numbers and other features in the documentation up to date, which was unsuccessful.

Adding this pull request will require document editors to know a bit of Jamal, which complicates the markup being a hyper markup above the Asciidoc markup.

Release notes

Documentation processing is extended using Jamal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant