Shared Forgejo Actions workflow for Fedora Docs components

bookwar commented

2026-06-17 22:34:06 +00:00

I have tried to enable Forgejo Actions for Fedora Council Docs repository, and while basic CI setup I copied from Fedora Infrastructure Docs works, we immediately hit the issue:

our docs are split in the components, and the components are not complete. Thus when trying to build the preview of one component in isolation, we get CI errors.

To solve this problem we need to have a shared CI concept which verifies the change in one of the components by building the entire docs site.

Currently we have a CI container with the antora tool https://forge.fedoraproject.org/infra/docs/src/branch/main/.forgejo/workflows/docs.yml#L9

We run that container in the CI workflow, the tool downloads git sources and runs the build.

If we try to build the entire Fedora Docs site this way on every pull request, the antora engine would need to fetch data from multiple git repositories, and the build will take too long. We need to optimize the build so that it doesn't need to download so many git sources.

Proposal:

We setup the workflow in the main fedora docs site, so that every time it builds the site and pushes it to production, it also builds a container with the antora tool, all git sources from all Fedora Docs components, and the one full build of the docs site. It means that container image will include all cached data and all sources of all latest branches of the Fedora Docs components.

The component level CI then will use that container as a base, add a new code from the pull request to that component repository and run the full build of the Fedora Docs side.

This way we will run full Fedora Docs site build on every pull request in every component, but because the git sources and caches will be included in the base container image, the test run will still be fast.

I have tried to enable Forgejo Actions for Fedora Council Docs repository, and while basic CI setup I copied from Fedora Infrastructure Docs works, we immediately hit the issue: our docs are split in the components, and the components are not complete. Thus when trying to build the preview of one component in isolation, we get CI errors. To solve this problem we need to have a shared CI concept which verifies the change in one of the components by building the entire docs site. --- Currently we have a CI container with the antora tool https://forge.fedoraproject.org/infra/docs/src/branch/main/.forgejo/workflows/docs.yml#L9 We run that container in the CI workflow, the tool downloads git sources and runs the build. If we try to build the entire Fedora Docs site this way on every pull request, the antora engine would need to fetch data from multiple git repositories, and the build will take too long. We need to optimize the build so that it doesn't need to download so many git sources. --- Proposal: We setup the workflow in the main fedora docs site, so that every time it builds the site and pushes it to production, it also builds a container with the antora tool, all git sources from all Fedora Docs components, and the one full build of the docs site. It means that container image will include all cached data and all sources of all latest branches of the Fedora Docs components. The component level CI then will use that container as a base, add a new code from the pull request to that component repository and run the full build of the Fedora Docs side. This way we will run full Fedora Docs site build on every pull request in every component, but because the git sources and caches will be included in the base container image, the test run will still be fast.

pboy added the

labels

2026-06-21 10:56:04 +00:00

pboy added this to the (deleted) project

2026-06-21 10:56:11 +00:00

pbokoc was assigned by pboy

2026-06-21 10:56:40 +00:00

pbokoc was unassigned by hricky

2026-06-22 20:34:07 +00:00

hricky self-assigned this

2026-06-22 20:34:08 +00:00

hricky commented

2026-06-23 05:55:32 +00:00

Member

The usual workflow for previewing changes to docs is to run docsbuilder.sh in your local clone of the repo. I tested it and it builds and previews both Infra and Council docs. What is the purpose of building Infra and Council docs in a CI?

The usual workflow for previewing changes to docs is to run `docsbuilder.sh` in your local clone of the repo. I tested it and it builds and previews both Infra and Council docs. What is the purpose of building Infra and Council docs in a CI?

pboy modified the project from (deleted) to Fedora Forge for Docs Automation

2026-06-25 11:32:12 +00:00

jflory7 referenced this issue

2026-06-29 18:23:43 +00:00

Monitoring and incident reporting for docs site builds (prod and stg) #53

jflory7 referenced this issue

2026-06-29 22:34:18 +00:00

Outdated docsbuilder.sh pulls Antora container w/ EOL nodejs #19

jflory7 added the

meeting topic

label

2026-06-29 22:35:04 +00:00

jflory7 commented

2026-06-29 22:35:49 +00:00

Owner

Added meeting topic label for 30 June, 2026 Fedora Docs Team meeting.

Added [`meeting topic`](https://forge.fedoraproject.org/docs/tickets/issues?labels=5631) label for 30 June, 2026 Fedora Docs Team meeting.

bookwar commented

2026-06-29 22:40:43 +00:00

Author

What is the purpose of building Infra and Council docs in a CI?

It makes editing docs more accessible.

Forgejo interface allows you to create a change in a docs repo without checking out anything on a local machine. You can use the "Edit file" functionality of a web ui even when you don't know how to use Git and how to run scripts.

Make a change with an editor, create a PR, get the CI result, review it, merge the pr.

It makes the process cleaner and more reliable.

No issues like "forgot to rebase the PR to the latest state of the branch before review, Or forgot to clean cache befor ebuilding, or used a worng version of the tooling. There is always one shared source of truth about what was tested and was reviewed.

> What is the purpose of building Infra and Council docs in a CI? 1) It makes editing docs more accessible. Forgejo interface allows you to create a change in a docs repo without checking out anything on a local machine. You can use the "Edit file" functionality of a web ui even when you don't know how to use Git and how to run scripts. Make a change with an editor, create a PR, get the CI result, review it, merge the pr. 2) It makes the process cleaner and more reliable. No issues like "forgot to rebase the PR to the latest state of the branch before review, Or forgot to clean cache befor ebuilding, or used a worng version of the tooling. There is always one shared source of truth about what was tested and was reviewed.

brettweir commented

2026-06-30 08:36:58 +00:00

I'm dumping my thoughts on this specific issue and various other things since I can't attend the meeting. Sorry if this is off-topic.

I preface my feedback here with an acknowledgement that I am new to the community and do not have broad/deep visibility into what's going on in various projects or where the skeletons lie.

It feels like a code smell that a CI build of a doc component would fail because other doc components are not available. If the preview is for a primary entrypoint, like the Project That Builds Them All and provides a container for all the components, this outcome makes more sense to me.

I have noted a docsbuilder.sh script that appears everywhere. The concept is great and essential, because Antora does not provide a hot-reloading mechanism and is fiddly to configure. I have implemented similar for Sphinx in the past. What troubles me is that the code for docsbuilder.sh is significant and seems to be copy/pasted around to different projects. This orphans each copy of the script and ensures that each component project has a different experience interacting with it.

I've also noted that the docs projects I've encountered so far (not many), seem to be buildable just fine without the need to download additional projects. If docsbuilder.sh downloads them transparently in the background, then I've overlooked that. I expect docs components to be self-contained, and to have a uniform interface for interacting with them, so that any docs project I jump into, I can hack on it immediately with the tools I already have, I can get fast feedback both from pre-commit hooks and later CI/CD, and the changes that I make in a branch or on main are quickly and routinely verified before they ever have a chance to impact downstream projects.

With that in mind, I see a few ideas for how all of this would take shape:

docsbuilder.sh becomes a tool. Clearly the Antora local experience is lacking and this presents an unmet need that we can fill. docsbuilder.sh becomes, I dunno, antora-hotdev or antoritup or whatever, package the script in a Python package (or rewrite in Python), publish on Forge PyPI (or real PyPI), now everyone can pip install antoratime.

Or, oh, fedantry! Get it? fedora + antora = fedantora? I digress...

The local experience becomes:

$ pip install --extra-index-url forge.fedoraproject.org... fedantora
$ fedantora serve
congrats u runnin' now at http://127.0.0.1:1337 ...
^C
$ fedantora build
buildin' for production yo

Now, since fedantora has a million ruby dependencies and probably a rendering library somewhere, it realistically needs to be distributed as a container. This may easier for people than consuming Forge packages directly:

So now it's:

$ podman run --rm -ti -v `pwd`:/build -w /build fedantora serve
congrats u runnin' now at http://127.0.0.1:1337 ...
^C
$ podman run --rm -ti -v `pwd`:/build -w /build fedantora build
buildin' for production yo

Since fedantora is a well-formed Python CLI (since we packaged it for PyPI), it should be marvelously easy to distribute as a pre-commit hook; just add .pre-commit-hooks.yaml to the fedantora repository, and now consumers can add the hook to their repository like so:

# .pre-commit-config.yaml
repos:
  - repo: forge.fedoraproject.org/fedantora/location
    ref: "1.2.3"
    hooks:
      - fedantora-build # test that the docs build before commiting

Since fedantora is distributed as a container for easy time, it's easy enough to write a shared workflow. I'm less fluent in Actions so I'm going to pseudo-action it:

# .forgejo/actions/fedantora.yml
# I haven't looked up the syntax, bear with me, I need to sleep
jobs:
  fedantora-build:
    uses: forge.fedoraproject.org/fedantora/location:1.2.3
    steps:
      - action: git/checkout@v4
      - fedantora --version
      - fedantora build
      - action: save/artifacts/somewhere@v1

This could be consumed as-is (hopefully after it's real), or you can then go the extra step to make it a fully-formed action. The advantage of consuming the shared workflow is that it encourages use of the pipeline as-is without modification, and people don't have to add a bunch of scaffolding just to run a single action. (This is a major beef I have with Actions' step-wise granularity vs. GitLab CI/CD's job-wise granularity). GitHub allows you to do this across repositories. I'm not sure if ForgeJo supports this yet. It looks something like this:

jobs:
  fedora-build:
    uses: fedantora/location/.forgejo/workflows/fedantora-build.yml

Whether this exists or not, I'd keep the doc component boilerplate as minimal as possible, make docsbuilder.sh a tool, containerize it, and bug everyone until each docs project is using this directly and building a self-contained version of their site on every commit.

I realize now that I may not be directly responding to this issue, but this is what comes to mind.

I'm dumping my thoughts on this specific issue and various other things since I can't attend the meeting. Sorry if this is off-topic. I preface my feedback here with an acknowledgement that I am new to the community and do not have broad/deep visibility into what's going on in various projects or where the skeletons lie. It feels like a code smell that a CI build of a doc component would fail because other doc components are not available. If the preview is for a primary entrypoint, like the Project That Builds Them All and provides a container for all the components, this outcome makes more sense to me. I have noted a docsbuilder.sh script that appears everywhere. The concept is great and essential, because Antora does not provide a hot-reloading mechanism and is fiddly to configure. I have implemented similar for Sphinx in the past. What troubles me is that the code for docsbuilder.sh is significant and seems to be copy/pasted around to different projects. This orphans each copy of the script and ensures that each component project has a different experience interacting with it. I've also noted that the docs projects I've encountered so far (not many), seem to be buildable just fine without the need to download additional projects. If docsbuilder.sh downloads them transparently in the background, then I've overlooked that. I expect docs components to be self-contained, and to have a uniform interface for interacting with them, so that any docs project I jump into, I can hack on it immediately with the tools I already have, I can get fast feedback both from pre-commit hooks and later CI/CD, and the changes that I make in a branch or on main are quickly and routinely verified before they ever have a chance to impact downstream projects. With that in mind, I see a few ideas for how all of this would take shape: docsbuilder.sh becomes a tool. Clearly the Antora local experience is lacking and this presents an unmet need that we can fill. docsbuilder.sh becomes, I dunno, antora-hotdev or antoritup or whatever, package the script in a Python package (or rewrite in Python), publish on Forge PyPI (or real PyPI), now everyone can pip install antoratime. > Or, oh, `fedantry`! Get it? fedora + antora = **fedantora**? I digress... The local experience becomes: ```console $ pip install --extra-index-url forge.fedoraproject.org... fedantora $ fedantora serve congrats u runnin' now at http://127.0.0.1:1337 ... ^C $ fedantora build buildin' for production yo ``` Now, since fedantora has a million ruby dependencies and probably a rendering library somewhere, it realistically needs to be distributed as a container. This may easier for people than consuming Forge packages directly: So now it's: ```console $ podman run --rm -ti -v `pwd`:/build -w /build fedantora serve congrats u runnin' now at http://127.0.0.1:1337 ... ^C $ podman run --rm -ti -v `pwd`:/build -w /build fedantora build buildin' for production yo ``` Since fedantora is a well-formed Python CLI (since we packaged it for PyPI), it should be marvelously easy to distribute as a pre-commit hook; just add .pre-commit-hooks.yaml to the fedantora repository, and now consumers can add the hook to their repository like so: ```yaml # .pre-commit-config.yaml repos: - repo: forge.fedoraproject.org/fedantora/location ref: "1.2.3" hooks: - fedantora-build # test that the docs build before commiting ``` Since fedantora is distributed as a container for easy time, it's easy enough to write a shared workflow. I'm less fluent in Actions so I'm going to pseudo-action it: ```yaml # .forgejo/actions/fedantora.yml # I haven't looked up the syntax, bear with me, I need to sleep jobs: fedantora-build: uses: forge.fedoraproject.org/fedantora/location:1.2.3 steps: - action: git/checkout@v4 - fedantora --version - fedantora build - action: save/artifacts/somewhere@v1 ``` This could be consumed as-is (hopefully after it's real), or you can then go the extra step to make it a fully-formed action. The advantage of consuming the shared workflow is that it encourages use of the pipeline as-is without modification, and people don't have to add a bunch of scaffolding just to run a single action. (This is a _major_ beef I have with Actions' step-wise granularity vs. GitLab CI/CD's job-wise granularity). GitHub allows you to do this across repositories. I'm not sure if ForgeJo supports this yet. It looks something like this: ```yaml jobs: fedora-build: uses: fedantora/location/.forgejo/workflows/fedantora-build.yml ``` Whether this exists or not, I'd keep the doc component boilerplate as minimal as possible, make docsbuilder.sh a tool, containerize it, and bug everyone until each docs project is using this directly and building a self-contained version of their site on every commit. I realize now that I may not be directly responding to this issue, but this is what comes to mind.

hricky commented

2026-06-30 15:40:01 +00:00

Member

AFAIUI, this concept relies on building container images in Fedora Forge runners, which is not currently possible, nor recommended by the Fedora Forge team.

docsbuilder.sh is a separate topic that can be followed at #19.

AFAIUI, this concept relies on building container images in Fedora Forge runners, which is not currently possible, nor recommended by the Fedora Forge team. `docsbuilder.sh` is a separate topic that can be followed at #19.

bookwar commented

2026-06-30 15:55:58 +00:00

Author

AFAIUI, this concept relies on building container images in Fedora Forge runners, which is not currently possible, nor recommended by the Fedora Forge team.

We would only need to build the "main container" in a separate pipeline, which does the build of the main Fedora Docs site and publishes the result to the docs.fedoraproject.org. So it is already a trusted content built in a much more secure environment.

I am not sure where it is done today, but it might be done by a cron job even or a Jenkins pipeline, not triggered by Forge events.

Using this workflow on the Forge side we would not build the container on any of the pull-request checks in any of the docs repositories. All docs repositories would use simple and cheap Forgejo Actions, which would use the same periodically updated main container as an immutable base for their CI runs.

> AFAIUI, this concept relies on building container images in Fedora Forge runners, which is not currently possible, nor recommended by the Fedora Forge team. We would only need to build the "main container" in a separate pipeline, which does the build of the main Fedora Docs site and publishes the result to the docs.fedoraproject.org. So it is already a trusted content built in a much more secure environment. I am not sure where it is done today, but it might be done by a cron job even or a Jenkins pipeline, not triggered by Forge events. Using this workflow on the Forge side we would not build the container on any of the pull-request checks in any of the docs repositories. All docs repositories would use simple and cheap Forgejo Actions, which would use the same periodically updated main container as an immutable base for their CI runs.

hricky commented

2026-06-30 16:20:33 +00:00

Member

I'm trying to understand what the end goal here is, so please bear with me. The Docs site is built by a Python script on a schedule. Every hour for the en-us site, and once a day for translated versions. Basically, the script pulls every repo from sources and builds the entire site. When a PR is merged, regardless of how the edits in the code are made, it is pulled by the builder script and the changes are visible on the site in about an hour.

When we modify the content of the module we are working on, we do it independently from other docs modules that form the entire Docs site. Every conflict that may occur is within the scope of the repo. The docs site building process does not know what the repos it pulls contain. For example, if a repo is moved to Fedora Forge and the old one is deleted or emptied, the build of the whole site will break because the config still refers to the old repo source. That happened a few days ago.

So, adding a CI for the repo that builds the whole site may make sense, for checking the logs, although it will not prevent the build failures. We may also consider adding a CI in the individual docs repos and set them to not merge until the build test passes. We need to check if this is possible, though.

Does this correspond in any way to the proposal?

I'm trying to understand what the end goal here is, so please bear with me. The Docs site is built by a Python script on a schedule. Every hour for the en-us site, and once a day for translated versions. Basically, the script pulls every repo from sources and builds the entire site. When a PR is merged, regardless of how the edits in the code are made, it is pulled by the builder script and the changes are visible on the site in about an hour. When we modify the content of the module we are working on, we do it independently from other docs modules that form the entire Docs site. Every conflict that may occur is within the scope of the repo. The docs site building process does not know what the repos it pulls contain. For example, if a repo is moved to Fedora Forge and the old one is deleted or emptied, the build of the whole site will break because the config still refers to the old repo source. That happened a few days ago. So, adding a CI for the repo that builds the whole site may make sense, for checking the logs, although it will not prevent the build failures. We may also consider adding a CI in the individual docs repos and set them to not merge until the build test passes. We need to check if this is possible, though. Does this correspond in any way to the proposal?

bookwar commented

2026-06-30 16:56:47 +00:00

Author

the script pulls every repo from sources and builds the entire site

The proposal is to save the environment from which this script runs and all artifacts it produced into a public container image, so that Forgejo Actions in all other doc repositories can reuse it for the base of their CI runs.

The script pulls all code from all modules, runs the build, that build -> we save it all as an image and publish to quay.io.

When we modify the content of the module we are working on, we do it independently from other docs modules that form the entire Docs site

This is the core issue. The content we add to the modules is managed by individual teams and individual reviewers, which is good. But we need CI to make sure that this individual modules are actually aligned enough so that they can be built in a single big doc site. Currently we do not have any mechanics preventing an owner of a module from accidentally breaking that compatibility. Shared CI approach would allow to enforce it.

adding a CI for the repo that builds the whole site may make sense, for checking the logs, although it will not prevent the build failures.

The proposal is not to add CI for the main repo (the one which builds the main site). The proposal is to use the artifact built by the CI of the main repo to create CI pipelines in each repo of each module in the same unified manner.

Let me take a step back and explain in details the specific issue which triggered the request:

There is a tiny PR in the fedora council docs repo which needed a review. I reviewed it and it made sense but I was not sure if the asciidoc syntax would work correctly. I could have made a local git clone of the repo, than install local dependencies, then run a local build, then check if the rendering is correct. But that is quite a lot of work. If I had a CI I would just click a link, browse the result, and merge the PR.

So I tried to add the CI to the repo to do just that.

I copied the Forgejo Action from the infra/docs repository and it looked quite simple: run a base image, checkout the code from council/docs repo, run a build. And that CI pipeline worked council/docs#290

But the CI run itself failed, because when you build a single module, like council/docs, without the rest of the content, the links to other modules can not be resolved.

ERROR (asciidoctor): target of xref not found: mindshare-committee::index.adoc
    file: /workspace/council/docs/project/modules/ROOT/pages/leadership.adoc
    source: /workspace/council/docs (branch: HEAD <worktree> | start path: project)

We could simply ignore such errors, but working cross-references is one of the important parts of the maintaining the documentation in a good shape. So the information on when the link can not be resolved is valuable for the PR review.

So to resolve this issue properly we need the links to other doc modules to be present, when we build the current module.

The easiest way to do it is to have all the linked modules available on the filesystem when you do a build of the current module.

But trying to check all the modules from the internet every time when you run a build for a specific PR in a specific module would require quite a lot of time.

So my idea is that we should have a pre-built container image produced by the main piepline, which would have the content of all Fedora docs already pre-baked. Which means all of those targets for xref would be present in that container image.

So the CI run on an individual PR would be:

run a pre-built image with all dependencies and all doc sources for all modules already included
checkout the update from a specific PR on top of the one of the modules, in this case - council/docs
run the full build of the docs site from the local filesystem not fetching any updates from the internet
get the full preview of the docs site
report the result

Instead of the current:

run a generic image
install docs dependencies
checkout council/docs code
build the council/docs only with the module specific build script
get a failure for the cross-references not working

> the script pulls every repo from sources and builds the entire site The proposal is to save the environment from which this script runs and all artifacts it produced into a public container image, so that Forgejo Actions in all other doc repositories can reuse it for the base of their CI runs. The script pulls all code from all modules, runs the build, that build -> we save it all as an image and publish to quay.io. > When we modify the content of the module we are working on, we do it independently from other docs modules that form the entire Docs site This is the core issue. The content we add to the modules is managed by individual teams and individual reviewers, which is good. But we need CI to make sure that this individual modules are actually aligned enough so that they can be built in a single big doc site. Currently we do not have any mechanics preventing an owner of a module from accidentally breaking that compatibility. Shared CI approach would allow to enforce it. > adding a CI for the repo that builds the whole site may make sense, for checking the logs, although it will not prevent the build failures. The proposal is not to add CI for the main repo (the one which builds the main site). The proposal is to use the artifact built by the CI of the main repo to create CI pipelines in each repo of each module in the same unified manner. ---- Let me take a step back and explain in details the specific issue which triggered the request: There is a tiny PR in the fedora council docs repo which needed a review. I reviewed it and it made sense but I was not sure if the asciidoc syntax would work correctly. I could have made a local git clone of the repo, than install local dependencies, then run a local build, then check if the rendering is correct. But that is quite a lot of work. If I had a CI I would just click a link, browse the result, and merge the PR. So I tried to add the CI to the repo to do just that. I copied the Forgejo Action from the infra/docs repository and it looked quite simple: run a base image, checkout the code from council/docs repo, run a build. And that CI pipeline worked https://forge.fedoraproject.org/council/docs/pulls/290 But the CI run itself failed, because when you build a single module, like council/docs, without the rest of the content, the links to other modules can not be resolved. ``` ERROR (asciidoctor): target of xref not found: mindshare-committee::index.adoc file: /workspace/council/docs/project/modules/ROOT/pages/leadership.adoc source: /workspace/council/docs (branch: HEAD <worktree> | start path: project) ``` We could simply ignore such errors, but working cross-references is one of the important parts of the maintaining the documentation in a good shape. So the information on when the link can not be resolved is valuable for the PR review. So to resolve this issue properly we need the links to other doc modules to be present, when we build the current module. The easiest way to do it is to have all the linked modules available on the filesystem when you do a build of the current module. But trying to check all the modules from the internet every time when you run a build for a specific PR in a specific module would require quite a lot of time. So my idea is that we should have a pre-built container image produced by the main piepline, which would have the content of all Fedora docs already pre-baked. Which means all of those targets for xref would be present in that container image. So the CI run on an individual PR would be: 1) run a pre-built image with all dependencies and all doc sources for all modules already included 2) checkout the update from a specific PR on top of the one of the modules, in this case - council/docs 3) run the full build of the docs site from the local filesystem not fetching any updates from the internet 4) get the full preview of the docs site 4) report the result Instead of the current: 1) run a generic image 2) install docs dependencies 3) checkout council/docs code 4) build the council/docs only with the module specific build script 5) get a failure for the cross-references not working

jflory7 commented

2026-06-30 17:13:55 +00:00

Owner

@brettweir wrote in #49 (comment):

docsbuilder.sh becomes a tool. Clearly the Antora local experience is lacking and this presents an unmet need that we can fill. docsbuilder.sh becomes, I dunno, antora-hotdev or antoritup or whatever, package the script in a Python package (or rewrite in Python), publish on Forge PyPI (or real PyPI), now everyone can pip install antoratime.

We definitely still need a script which targets the local development workflow. Being able to run a script, auto-magically grab the right containers and other software bits, and get a local preview in the browser while editing is important.

@brettweir wrote in #49 (comment):

Or, oh, fedantry! Get it? fedora + antora = fedantora? I digress...

The local experience becomes:
$ pip install --extra-index-url forge.fedoraproject.org... fedantora
$ fedantora serve
congrats u runnin' now at http://127.0.0.1:1337 ...
^C
$ fedantora build
buildin' for production yo

Is this a possible tool you are considering to build?

@brettweir wrote in #49 (comment):

Now, since fedantora has a million ruby dependencies and probably a rendering library somewhere, it realistically needs to be distributed as a container. This may easier for people than consuming Forge packages directly:

So now it's:
$ podman run --rm -ti -v `pwd`:/build -w /build fedantora serve
congrats u runnin' now at http://127.0.0.1:1337 ...
^C
$ podman run --rm -ti -v `pwd`:/build -w /build fedantora build
buildin' for production yo

Ideally, the runtime is distributed as a container. We used to rely on editors using Fedora Linux in the past and having access to Fedora RPM packages, but we should consider that people use all kinds of different platforms and operating systems to contribute. And that's okay! So, containers work better here.

@brettweir wrote in #49 (comment):

Since fedantora is a well-formed Python CLI (since we packaged it for PyPI), it should be marvelously easy to distribute as a pre-commit hook; just add .pre-commit-hooks.yaml to the fedantora repository, and now consumers can add the hook to their repository like so:
# .pre-commit-config.yaml
repos:
  - repo: forge.fedoraproject.org/fedantora/location
    ref: "1.2.3"
    hooks:
      - fedantora-build # test that the docs build before commiting

I have found pre-commit hooks to create a lot of overhead for project committers, particularly people who may not be using a terminal or editor workflow to make changes. Some people may be committing directly from the web interface, which we should consider.

@brettweir wrote in #49 (comment):

Since fedantora is distributed as a container for easy time, it's easy enough to write a shared workflow. I'm less fluent in Actions so I'm going to pseudo-action it:

# .forgejo/actions/fedantora.yml
# I haven't looked up the syntax, bear with me, I need to sleep
jobs:
  fedantora-build:
    uses: forge.fedoraproject.org/fedantora/location:1.2.3
    steps:
      - action: git/checkout@v4
      - fedantora --version
      - fedantora build
      - action: save/artifacts/somewhere@v1

I am not sure I understand why the fedantora tool is needed for the CI pipeline versus how we already do things?

@brettweir wrote in #49 (comment):

This could be consumed as-is (hopefully after it's real), or you can then go the extra step to make it a fully-formed action. The advantage of consuming the shared workflow is that it encourages use of the pipeline as-is without modification, and people don't have to add a bunch of scaffolding just to run a single action. (This is a major beef I have with Actions' step-wise granularity vs. GitLab CI/CD's job-wise granularity). GitHub allows you to do this across repositories. I'm not sure if ForgeJo supports this yet. It looks something like this:

One idea I was thinking about lately is what a "push" model might look like for Fedora Docs instead of a "pull" model. What if we had individual repositories use CI to successfully build the assets locally, and then deploy them to the production server for the static HTML on the Fedora Docs site? I'm not sure how cross-ref links would work in this scenario though, if the site is not built all together at once.

It is always a wish of mine to have updates dynamically get built once a docs repo successfully runs CI, and then the changes are immediately pushed to the production site.

@brettweir wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020: > docsbuilder.sh becomes a tool. Clearly the Antora local experience is lacking and this presents an unmet need that we can fill. docsbuilder.sh becomes, I dunno, antora-hotdev or antoritup or whatever, package the script in a Python package (or rewrite in Python), publish on Forge PyPI (or real PyPI), now everyone can pip install antoratime. We definitely still need a script which targets the local development workflow. Being able to run a script, auto-magically grab the right containers and other software bits, and get a local preview in the browser while editing is important. @brettweir wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020: > > Or, oh, `fedantry`! Get it? fedora + antora = **fedantora**? I digress... > > The local experience becomes: > > ```console > $ pip install --extra-index-url forge.fedoraproject.org... fedantora > $ fedantora serve > congrats u runnin' now at http://127.0.0.1:1337 ... > ^C > $ fedantora build > buildin' for production yo > ``` Is this a possible tool you are considering to build? @brettweir wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020: > Now, since fedantora has a million ruby dependencies and probably a rendering library somewhere, it realistically needs to be distributed as a container. This may easier for people than consuming Forge packages directly: > > So now it's: > > ```console > $ podman run --rm -ti -v `pwd`:/build -w /build fedantora serve > congrats u runnin' now at http://127.0.0.1:1337 ... > ^C > $ podman run --rm -ti -v `pwd`:/build -w /build fedantora build > buildin' for production yo > ``` Ideally, the runtime is distributed as a container. We used to rely on editors using Fedora Linux in the past and having access to Fedora RPM packages, but we should consider that people use all kinds of different platforms and operating systems to contribute. And that's okay! So, containers work better here. @brettweir wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020: > Since fedantora is a well-formed Python CLI (since we packaged it for PyPI), it should be marvelously easy to distribute as a pre-commit hook; just add .pre-commit-hooks.yaml to the fedantora repository, and now consumers can add the hook to their repository like so: > > ```yaml > # .pre-commit-config.yaml > repos: > - repo: forge.fedoraproject.org/fedantora/location > ref: "1.2.3" > hooks: > - fedantora-build # test that the docs build before commiting > ``` I have found pre-commit hooks to create a lot of overhead for project committers, particularly people who may not be using a terminal or editor workflow to make changes. Some people may be committing directly from the web interface, which we should consider. @brettweir wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020: > Since fedantora is distributed as a container for easy time, it's easy enough to write a shared workflow. I'm less fluent in Actions so I'm going to pseudo-action it: > > ```yaml > # .forgejo/actions/fedantora.yml > # I haven't looked up the syntax, bear with me, I need to sleep > jobs: > fedantora-build: > uses: forge.fedoraproject.org/fedantora/location:1.2.3 > steps: > - action: git/checkout@v4 > - fedantora --version > - fedantora build > - action: save/artifacts/somewhere@v1 > ``` I am not sure I understand why the `fedantora` tool is needed for the CI pipeline versus how we already do things? @brettweir wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020: > This could be consumed as-is (hopefully after it's real), or you can then go the extra step to make it a fully-formed action. The advantage of consuming the shared workflow is that it encourages use of the pipeline as-is without modification, and people don't have to add a bunch of scaffolding just to run a single action. (This is a _major_ beef I have with Actions' step-wise granularity vs. GitLab CI/CD's job-wise granularity). GitHub allows you to do this across repositories. I'm not sure if ForgeJo supports this yet. It looks something like this: One idea I was thinking about lately is what a "push" model might look like for Fedora Docs instead of a "pull" model. What if we had individual repositories use CI to successfully build the assets locally, and then deploy them to the production server for the static HTML on the Fedora Docs site? I'm not sure how cross-ref links would work in this scenario though, if the site is not built all together at once. It is always a wish of mine to have updates dynamically get built once a docs repo successfully runs CI, and then the changes are immediately pushed to the production site.

jflory7 commented

2026-06-30 17:33:13 +00:00

Owner

Discussed in 2026-06-30 Fedora Docs Team meeting.

Ticket #49 received a brief mention during today's meeting. @pbokoc highlighted a new comment from Brett and asked everyone interested in CI to review it asynchronously. @hricky indicated he will also comment in the ticket after the meeting.

HELP WANTED: Review Brett's comment and share feedback asynchronously

_{Assisted-by: Claude Opus 4.6 (1M context)}

_Discussed in [2026-06-30 Fedora Docs Team meeting](https://discussion.fedoraproject.org/t/fedora-docs-team-meeting-2026-06-30/195195/3)._ --- Ticket #49 received a brief mention during today's meeting. @pbokoc highlighted a [new comment from Brett](https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-872020) and asked everyone interested in CI to review it asynchronously. @hricky indicated he will also comment in the ticket after the meeting. - **HELP WANTED:** Review Brett's comment and share feedback asynchronously <sub>_Assisted-by: Claude Opus 4.6 (1M context)_</sub>

hricky commented

2026-06-30 18:48:11 +00:00

Member

@bookwar wrote in #49 (comment):

So my idea is that we should have a pre-built container image produced by the main piepline, which would have the content of all Fedora docs already pre-baked. Which means all of those targets for xref would be present in that container image.

I think I'm starting to understand now and the idea makes sense. If we're going to build a container image that contains all the docs sources, it should be for the English versions only, otherwise it will be too big. I'll try to build such an image.

@bookwar wrote in #49 (comment):

So the CI run on an individual PR would be:

run a pre-built image with all dependencies and all doc sources for all modules already included

checkout the update from a specific PR on top of the one of the modules, in this case - council/docs

run the full build of the docs site from the local filesystem not fetching any updates from the internet

get the full preview of the docs site

report the result

I'll test this or similar workflow and post an update when I get some results.

@bookwar wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874240: > So my idea is that we should have a pre-built container image produced by the main piepline, which would have the content of all Fedora docs already pre-baked. Which means all of those targets for xref would be present in that container image. I think I'm starting to understand now and the idea makes sense. If we're going to build a container image that contains all the docs sources, it should be for the English versions only, otherwise it will be too big. I'll try to build such an image. @bookwar wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874240: > So the CI run on an individual PR would be: > 1. run a pre-built image with all dependencies and all doc sources for all modules already included > 2. checkout the update from a specific PR on top of the one of the modules, in this case - council/docs > 3. run the full build of the docs site from the local filesystem not fetching any updates from the internet > 4. get the full preview of the docs site > 5. report the result I'll test this or similar workflow and post an update when I get some results.

❤️ 2

brettweir commented

2026-07-01 08:54:09 +00:00

@jflory7 wrote in #49 (comment):

@brettweir wrote in #49 (comment):

docsbuilder.sh becomes a tool. Clearly the Antora local experience is lacking and this presents an unmet need that we can fill. docsbuilder.sh becomes, I dunno, antora-hotdev or antoritup or whatever, package the script in a Python package (or rewrite in Python), publish on Forge PyPI (or real PyPI), now everyone can pip install antoratime.

We definitely still need a script which targets the local development workflow. Being able to run a script, auto-magically grab the right containers and other software bits, and get a local preview in the browser while editing is important.

In this proposal, I'm not suggesting doing away with docsbuilder.sh, but rather the opposite: immortalize and glorify docsbuilder.sh by packaging it for distribution in common channels and ensuring it is tested, released, and versioned like any other software artifact, rather than existing as ad hoc versions in different projects. I want to give docsbuilder.sh a home.

@jflory7 wrote in #49 (comment):

@brettweir wrote in #49 (comment):
Or, oh, fedantry! Get it? fedora + antora = fedantora? I digress...

The local experience becomes:
$ pip install --extra-index-url forge.fedoraproject.org... fedantora
$ fedantora serve
congrats u runnin' now at http://127.0.0.1:1337 ...
^C
$ fedantora build
buildin' for production yo
Is this a possible tool you are considering to build?

I'd be super down to build it. @hricky expressed that he was already working on something in this vein, so I don't want to duplicate efforts, but I'd be happy to work with him or anyone else to develop the distribution path. I've done a lot of release engineering over the years, but I'm still learning where things live at Fedora and who does what, so I'm poking around blindly when looking for places to get involved. 😄

@jflory7 wrote in #49 (comment):

@brettweir wrote in #49 (comment):
Now, since fedantora has a million ruby dependencies and probably a rendering library somewhere, it realistically needs to be distributed as a container. This may easier for people than consuming Forge packages directly:
So now it's:
$ podman run --rm -ti -v `pwd`:/build -w /build fedantora serve
congrats u runnin' now at http://127.0.0.1:1337 ...
^C
$ podman run --rm -ti -v `pwd`:/build -w /build fedantora build
buildin' for production yo
Ideally, the runtime is distributed as a container. We used to rely on editors using Fedora Linux in the past and having access to Fedora RPM packages, but we should consider that people use all kinds of different platforms and operating systems to contribute. And that's okay! So, containers work better here.

Oh, for sure, it doesn't need to be coupled to Fedora. It absolutely can just be a container. Depending on the desired user experience, there could be a Python or Go CLI that makes calls to Docker/Podman, as well as making a ForgeJo workflow/action that consumes the container.

@jflory7 wrote in #49 (comment):

@brettweir wrote in #49 (comment):
Since fedantora is a well-formed Python CLI (since we packaged it for PyPI), it should be marvelously easy to distribute as a pre-commit hook; just add .pre-commit-hooks.yaml to the fedantora repository, and now consumers can add the hook to their repository like so:
# .pre-commit-config.yaml
repos:
  - repo: forge.fedoraproject.org/fedantora/location
    ref: "1.2.3"
    hooks:
      - fedantora-build # test that the docs build before commiting
I have found pre-commit hooks to create a lot of overhead for project committers, particularly people who may not be using a terminal or editor workflow to make changes. Some people may be committing directly from the web interface, which we should consider.

I've also had this experience and struggled with it. pre-commit hooks are awesome when everyone is bought into them, but there's a steep adoption curve that can alienate new users. I also like adding lots of linters to CI and that has a similar gating effect. That line is drawn differently depending on the community and I won't claim to know where that line is here.

@jflory7 wrote in #49 (comment):

@brettweir wrote in #49 (comment):
Since fedantora is distributed as a container for easy time, it's easy enough to write a shared workflow. I'm less fluent in Actions so I'm going to pseudo-action it:
# .forgejo/actions/fedantora.yml
# I haven't looked up the syntax, bear with me, I need to sleep
jobs:
  fedantora-build:
    uses: forge.fedoraproject.org/fedantora/location:1.2.3
    steps:
      - action: git/checkout@v4
      - fedantora --version
      - fedantora build
      - action: save/artifacts/somewhere@v1
I am not sure I understand why the fedantora tool is needed for the CI pipeline versus how we already do things?

As stated above, I don't believe what I'm proposing substantially changes the overall approach. It is a thin layer of packaging so that users have a consistent set of expectations regardless of the interaction point. Using fedantora/docsbuilder directly, using as a hook, using in CI as an action, you can expect to be able to build for production and run a live reload server anywhere the tool is available, so you can find out as early as possible whether you're on the right track with your changes.

@jflory7 wrote in #49 (comment):

@brettweir wrote in #49 (comment):

This could be consumed as-is (hopefully after it's real), or you can then go the extra step to make it a fully-formed action. The advantage of consuming the shared workflow is that it encourages use of the pipeline as-is without modification, and people don't have to add a bunch of scaffolding just to run a single action. (This is a major beef I have with Actions' step-wise granularity vs. GitLab CI/CD's job-wise granularity). GitHub allows you to do this across repositories. I'm not sure if ForgeJo supports this yet. It looks something like this:

One idea I was thinking about lately is what a "push" model might look like for Fedora Docs instead of a "pull" model. What if we had individual repositories use CI to successfully build the assets locally, and then deploy them to the production server for the static HTML on the Fedora Docs site? I'm not sure how cross-ref links would work in this scenario though, if the site is not built all together at once.

It is always a wish of mine to have updates dynamically get built once a docs repo successfully runs CI, and then the changes are immediately pushed to the production site.

That was something that frightened me away from Antora a few years ago, because coordinating across all these repos was never going to be fun. If the Fedora branding is packaged with the tool (fedantora lol), and your site configuration knows its relative path/to/where/hosted, you could take a lazy approach to cross-linking, and just run something like broken-link-checker in CI before publishing individual sites, so everything just publishes at its own pace. This works okay because access control is not an issue (everything is public), but it abandons hope of perfect accuracy in favor of expedience.

@jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874243: > @brettweir wrote in #49 (comment): > > > docsbuilder.sh becomes a tool. Clearly the Antora local experience is lacking and this presents an unmet need that we can fill. docsbuilder.sh becomes, I dunno, antora-hotdev or antoritup or whatever, package the script in a Python package (or rewrite in Python), publish on Forge PyPI (or real PyPI), now everyone can pip install antoratime. > > We definitely still need a script which targets the local development workflow. Being able to run a script, auto-magically grab the right containers and other software bits, and get a local preview in the browser while editing is important. In this proposal, I'm not suggesting doing away with docsbuilder.sh, but rather the opposite: immortalize and glorify docsbuilder.sh by packaging it for distribution in common channels and ensuring it is tested, released, and versioned like any other software artifact, rather than existing as ad hoc versions in different projects. **I want to give docsbuilder.sh a home.** @jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874243: > @brettweir wrote in #49 (comment): > > > > Or, oh, `fedantry`! Get it? fedora + antora = **fedantora**? I digress... > > > > > > The local experience becomes: > > ```console > > $ pip install --extra-index-url forge.fedoraproject.org... fedantora > > $ fedantora serve > > congrats u runnin' now at http://127.0.0.1:1337 ... > > ^C > > $ fedantora build > > buildin' for production yo > > ``` > > Is this a possible tool you are considering to build? I'd be super down to build it. @hricky expressed that he was already working on something in this vein, so I don't want to duplicate efforts, but I'd be happy to work with him or anyone else to develop the distribution path. I've done a lot of release engineering over the years, but I'm still learning where things live at Fedora and who does what, so I'm poking around blindly when looking for places to get involved. 😄 @jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874243: > @brettweir wrote in #49 (comment): > > > Now, since fedantora has a million ruby dependencies and probably a rendering library somewhere, it realistically needs to be distributed as a container. This may easier for people than consuming Forge packages directly: > > So now it's: > > ```console > > $ podman run --rm -ti -v `pwd`:/build -w /build fedantora serve > > congrats u runnin' now at http://127.0.0.1:1337 ... > > ^C > > $ podman run --rm -ti -v `pwd`:/build -w /build fedantora build > > buildin' for production yo > > ``` > > Ideally, the runtime is distributed as a container. We used to rely on editors using Fedora Linux in the past and having access to Fedora RPM packages, but we should consider that people use all kinds of different platforms and operating systems to contribute. And that's okay! So, containers work better here. Oh, for sure, it doesn't need to be coupled to Fedora. It absolutely can just be a container. Depending on the desired user experience, there could be a Python or Go CLI that makes calls to Docker/Podman, as well as making a ForgeJo workflow/action that consumes the container. @jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874243: > @brettweir wrote in #49 (comment): > > > Since fedantora is a well-formed Python CLI (since we packaged it for PyPI), it should be marvelously easy to distribute as a pre-commit hook; just add .pre-commit-hooks.yaml to the fedantora repository, and now consumers can add the hook to their repository like so: > > ```yaml > > # .pre-commit-config.yaml > > repos: > > - repo: forge.fedoraproject.org/fedantora/location > > ref: "1.2.3" > > hooks: > > - fedantora-build # test that the docs build before commiting > > ``` > > I have found pre-commit hooks to create a lot of overhead for project committers, particularly people who may not be using a terminal or editor workflow to make changes. Some people may be committing directly from the web interface, which we should consider. I've also had this experience and struggled with it. pre-commit hooks are awesome when everyone is bought into them, but there's a steep adoption curve that can alienate new users. I also like adding lots of linters to CI and that has a similar gating effect. That line is drawn differently depending on the community and I won't claim to know where that line is here. @jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874243: > @brettweir wrote in #49 (comment): > > > Since fedantora is distributed as a container for easy time, it's easy enough to write a shared workflow. I'm less fluent in Actions so I'm going to pseudo-action it: > > ```yaml > > # .forgejo/actions/fedantora.yml > > # I haven't looked up the syntax, bear with me, I need to sleep > > jobs: > > fedantora-build: > > uses: forge.fedoraproject.org/fedantora/location:1.2.3 > > steps: > > - action: git/checkout@v4 > > - fedantora --version > > - fedantora build > > - action: save/artifacts/somewhere@v1 > > ``` > > I am not sure I understand why the `fedantora` tool is needed for the CI pipeline versus how we already do things? As stated above, I don't believe what I'm proposing substantially changes the overall approach. It is a thin layer of packaging so that users have a consistent set of expectations regardless of the interaction point. Using fedantora/docsbuilder directly, using as a hook, using in CI as an action, you can expect to be able to build for production and run a live reload server anywhere the tool is available, so you can find out as early as possible whether you're on the right track with your changes. @jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/49#issuecomment-874243: > @brettweir wrote in #49 (comment): > > > This could be consumed as-is (hopefully after it's real), or you can then go the extra step to make it a fully-formed action. The advantage of consuming the shared workflow is that it encourages use of the pipeline as-is without modification, and people don't have to add a bunch of scaffolding just to run a single action. (This is a _major_ beef I have with Actions' step-wise granularity vs. GitLab CI/CD's job-wise granularity). GitHub allows you to do this across repositories. I'm not sure if ForgeJo supports this yet. It looks something like this: > > One idea I was thinking about lately is what a "push" model might look like for Fedora Docs instead of a "pull" model. What if we had individual repositories use CI to successfully build the assets locally, and then deploy them to the production server for the static HTML on the Fedora Docs site? I'm not sure how cross-ref links would work in this scenario though, if the site is not built all together at once. > > It is always a wish of mine to have updates dynamically get built once a docs repo successfully runs CI, and then the changes are immediately pushed to the production site. That was something that frightened me away from Antora a few years ago, because coordinating across all these repos was never going to be fun. If the Fedora branding is packaged with the tool (fedantora lol), and your site configuration knows its relative `path/to/where/hosted`, you could take a lazy approach to cross-linking, and just run something like [broken-link-checker](https://github.com/stevenvachon/broken-link-checker) in CI before publishing individual sites, so everything just publishes at its own pace. This works okay because access control is not an issue (everything is public), but it abandons hope of perfect accuracy in favor of expedience.

hricky commented

2026-07-01 12:52:10 +00:00

Member

Again, docsbuilder.sh is a separate topic, although it may also be somewhat related here. But let's discuss it at #19.

I think the current process of building the docs site in OpenShift is working well. Maybe we can improve it, but changes are not urgent and not on our schedule. This particular issue has a narrow scope, so let's concentrate on it.

Again, `docsbuilder.sh` is a separate topic, although it may also be somewhat related here. But let's discuss it at #19. I think the current process of building the docs site in OpenShift is working well. Maybe we can improve it, but changes are not urgent and not on our schedule. This particular issue has a narrow scope, so let's concentrate on it.