[x] Remove all old pdf generating supporting scripts in bin/linter, instructions_makepdf.md, makepdf, manual_config_pdf
[x] Removing the docs-pdf step from the pipeline
[x] Commenting the uploading pdf step in .drone.star
[x] Harmonize directory names for each extension (antora, asciidoc) + setting it correctly in site.yml
[x] Fix asciidoctor-kroki extension registration in site.yml
[x] Force cheerio to use the htmlparser2 engine - 6x more performant
This will take much less time in CI to finish the job freeing ressources - for EACH docs build
[x] Upgrade the pipeline to Node 18 as Node 16 is already EOL
[x] Check which CI envvars can be removed like BUILD_SEARCH_INDEX
see info below
[ ] Re-enable pdf generation
Skipping, see below
[ ] Pipline steps cleanup
Skipping, see below
Other repo dependent important notes/steps:
[x] All failing xrefs need to be resolved first - done with #89
[x] Check for the existence of attachmentsdir as with Antora 3 we can consistently use the family coordinate attachment$.
[ ] In the docs-main repo, we need to add runtime:log:failure_level: none in site.yml to avoid that CI will not get green because of erroring xrefs.
[ ] For the docs-server repo, we need to switch in the development manual for all versions where applicapable from ifeval::["{format}" == "html"] to ifndef::format[] because we have no longer the attribute defined in the build process (package.json). This attribute needs to be set to format=pdf to the antora build step when creating pdf's in future.
[ ] For the docs repo, we can remove BUILD_SEARCH_INDEX from .drone.star as it is no longer used.
"BUILD_SEARCH_INDEX": ctx.build.branch == deployment_branch, --> remove.
[ ] Need a docs repo upgrade for Node 18 and a comment that one needs to upgrade his local installation!
Embedded pdf generation:
While preparing to use the Antora Assembler (= pdf generation extension), it is necessary to have a working ruby environment we currently dont have in our owncloudci/nodejs:18 image. Post a discussion with @DeepDiver1975, we agreed to do this in an independent step, by creating a new image based on the node18 image. Having this we could remove the outdated/unused asciidoctor image.
This new image should:
preinstall ruby + necessary gems
omit not needed components like chrome
use Ubuntu 22.04 (currently 20.04)
preinstall all node modules required
use e.g. renovate to create dependency update PRs
...
This would bring a lot of benefits with one drawback
drawback:
we need to regulary check the image repo for available upgrade PRs
bonus:
no recurring installation of yarn and ruby dependencies on EACH CI run
(though we should run yarn install to see if any local deltas need an update - only small changes)
massive reduction of resources - network and CPU
reduction in image size
local upgrade testing --> onetime dependency merges
Pipline steps cleanup:
We will do this is in a later step to avoid delays.
Technically it is not a big deal but one needs to sit down and check .drone.star stuff in each docs repo
This upgrades Antora to version 3 (3.1.7 atm).
It is the first and template PR for other repos, except
docs-mainwhich needs special treatment.Tasks:
package.jsonso it has the latest Antora (3.1.7 atm)package.jsonto use the correct options for the Antora buildsBUILD_SEARCH_INDEXtriggered the indexing preperation stepxref-validatorjs code as this is now fully covered in the Antora build process, see https://gitlab.com/antora/xref-validatorxref-validatorstep from the pipelinegeneratordirectory as it is empty nowEdit-this-pagejs code from the generation code as this is now handled by Antora, see https://docs.antora.org/antora/latest/playbook/content-edit-url/#source-viewbin/linter,instructions_makepdf.md,makepdf,manual_config_pdfdocs-pdfstep from the pipeline.drone.starsite.ymlasciidoctor-krokiextension registration insite.ymlcheerioto use thehtmlparser2engine - 6x more performant This will take much less time in CI to finish the job freeing ressources - for EACH docs buildBUILD_SEARCH_INDEXsee info belowOther repo dependent important notes/steps:
attachment$.docs-mainrepo, we need to addruntime:log:failure_level: noneinsite.ymlto avoid that CI will not get green because of erroring xrefs.docs-serverrepo, we need to switch in the development manual for all versions where applicapable fromifeval::["{format}" == "html"]toifndef::format[]because we have no longer the attribute defined in the build process (package.json). This attribute needs to be set toformat=pdfto the antora build step when creating pdf's in future.docsrepo, we can removeBUILD_SEARCH_INDEXfrom.drone.staras it is no longer used."BUILD_SEARCH_INDEX": ctx.build.branch == deployment_branch,--> remove.docsrepo upgrade for Node 18 and a comment that one needs to upgrade his local installation!Embedded pdf generation:
owncloudci/nodejs:18image. Post a discussion with @DeepDiver1975, we agreed to do this in an independent step, by creating a new image based on the node18 image. Having this we could remove the outdated/unused asciidoctor image. This new image should:Pipline steps cleanup:
.drone.starstuff in each docs repo