Is your feature request related to a problem? Please describe.
In the scope of #1325 , we want to implement Doc-as-Code with AsciiDoc for the documentation of the usage and architecture of inspectIT Ocelot.
In this ticket, an appropriate static site generator for generating the documentation hosted at GitHub pages should be determined. Currently, we are using docusaurus to generate the static site for the usage documentation written in Markdown. However, docusaurus does not support AsciiDoc.
As we cannot use docusaurus, we need a static site generator that generates the sites automatically from the AsciiDoc (.adoc) files committed to the repository.
Importantly, we need versioning of the documentation so that the documentation can be found for each release version (as it is currently implemented with docusaurus).
The generation and versioning of the documentation currently happens in the CircleCi script (see https://github.com/inspectIT/inspectit-ocelot/blob/master/.circleci/config.yml).
Describe the solution you'd like
As a result, we'd like to know which static site generator (or GitHub Action/Plugin) can be used to generate the site on GitHub Pages from the AsciiDoc source files.
Describe alternatives you've considered
If none of the listed static site generators offers automatic versioning, we probably need to implement it by ourselves.
Additional context
Quick summary on how to use the doctoolchain to generate a static site for the arc42 template
create a project with a directory src/docs
cd into the docs directory
download docToolchain wrapper
wget doctoolchain.github.io/dtcw
for Windows, you need to
# run in Powershell
Invoke-WebRequest doctoolchain.github.io/dtcw.ps1 -Outfile dtcw.ps1
# alternatively, if supported, run
wget doctoolchain.github.io/dtcw.ps1
Is your feature request related to a problem? Please describe. In the scope of #1325 , we want to implement Doc-as-Code with AsciiDoc for the documentation of the usage and architecture of inspectIT Ocelot.
In this ticket, an appropriate static site generator for generating the documentation hosted at GitHub pages should be determined. Currently, we are using docusaurus to generate the static site for the usage documentation written in Markdown. However, docusaurus does not support AsciiDoc.
For the local development and testing, the doctoolchain can be used to generate the static website. You can follow the tutorial at https://av.tib.eu/media/52461 or http://doctoolchain.org/docToolchain/v2.0.x/. (You can find below a quick summary on how to generate a static site of the arc42 template).
As we cannot use docusaurus, we need a static site generator that generates the sites automatically from the AsciiDoc (
.adoc) files committed to the repository.Importantly, we need versioning of the documentation so that the documentation can be found for each release version (as it is currently implemented with docusaurus). The generation and versioning of the documentation currently happens in the CircleCi script (see https://github.com/inspectIT/inspectit-ocelot/blob/master/.circleci/config.yml).
A list of static site generators supporting AsciiDoc can be found here: https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d
Describe the solution you'd like As a result, we'd like to know which static site generator (or GitHub Action/Plugin) can be used to generate the site on GitHub Pages from the AsciiDoc source files.
Describe alternatives you've considered If none of the listed static site generators offers automatic versioning, we probably need to implement it by ourselves.
Additional context
Quick summary on how to use the doctoolchain to generate a static site for the arc42 template
create a project with a directory
src/docscdinto thedocsdirectorydownload docToolchain wrapper
for Windows, you need to
download the arc42 template
ywithhelpgenerate a static HTML site
open the generated HTML
to generate a more emphasized site, you can use
generateSite previewSite(see http://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/040_generateSite.html)