fedora-infrastructure

#8862 Fedora docs not rendering coreos page properly
Closed: Fixed by kevin. Opened by dustymabe.

Closed: Fixed
Reopen Issue

Describe what you would like us to do:

This page is showing up with garbage: https://docs.fedoraproject.org/en-US/fedora-coreos/update-streams/ . It shows plain html:

<div class="paragraph"> <p>Fedora CoreOS (FCOS) has several individual update streams that are available to end users. They are:</p> </div> <div class="ulist"> <ul> <li> <p><code>stable</code></p> <div class="ulist"> <ul> <li> <p>The <code>stable</code> stream is the most reliable stream offered with changes only reaching that stream after spending a period of time in the <code>testing</code> stream.</p> </li> </ul> </div> </li> <li> <p><code>testing</code></p> <div class="ulist"> <ul> <li> <p>The <code>testing</code> stream represents what is coming in the next <code>stable</code> release. Content in this stream is updated regularly and offers our community an opportunity to catch breaking changes before they hit the <code>stable</code> stream.</p> </li> </ul> </div> </li> <li> <p><code>next</code></p> <div class="ulist"> <ul> <li> <p>The <code>next</code> stream represents the future. It will often be used to experiment with new features and also test out rebases of our platform on top of the next major version of Fedora. The content in the <code>next</code> stream will also eventually filter down into <code>testing</code> and on to <code>stable</code>.</p> </li> </ul> </div> </li> </ul> </div> <div class="paragraph"> <p>When following a stream, a system is updated automatically when a new release is rolled out on that stream. While all streams of FCOS are automatically tested, it is strongly encouraged for users to devote a percentage of their FCOS deployment to running the <code>testing</code> and <code>next</code> streams. This ensures possible breaking changes can be caught early enough that <code>stable</code> deployments experience fewer regressions.</p> </div>

This page renders correctly when building the docs site locally: https://pagure.io/fedora-docs/docs-fp-o.git

If I compare the bad page with the good page I see:

<meta name="generator" content="Antora 2.3.0">

on the good page VS

<meta name="generator" content="Antora 2.0.1">

With the bad page. Can we get someone to investigate this to get a good looking page for release day?

When do you need this to be done by? (2020/04/28)

Before the F32 fedmag release annoucnement please!

cc @asamalik

Note that in the docs.fp.o repo there are two separate Dockerfiles (which increases confusion about the source of truth) and the build.sh also uses a different base image.

  • https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/Dockerfile
  • https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/build-scripts/Dockerfile
  • https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/build.sh#_3

Metadata Update from @smooge:
- Issue priority set to: Waiting on Assignee (was: Needs Review)
- Issue tagged with: websites-general

I think it's related to the fact Antora 2.3 was released.
We should just limit it to Antora 2.2 and it should go fine.
I don't know how to change that in docker file, but I can help confirm our global fedora-docs system still works.

I've seen this before; yes, limiting the docs toolchain to an earlier version of Antora would probably fix it, but that's because earlier versions of Antora were more permissive. The core of the problem is that the sources are marked up wrong. It's way too late right now in my timezone, but I'll go and fix it tomorrow.

I misread the issue

The antora version used by docs-fp-o is old: 2.0 and it creates generation errors.
With Antora 2.2 I don't see the error when doing a local preview.
The reporter don't see the error with Antora 2.3.

I think it's a good time for me to test the global fedora-docs website generation with Antora 2.2 or 2.3 (release 2.3 was a few days ago).
I understand the action required is to update the Dockerfile and make sure the generation still works. But this may be risky to change before release.

Thanks for helping look into this. Please let me know if there is anything I can do to help. We're planning to link to https://docs.fedoraproject.org/en-US/fedora-coreos/update-streams/ from the Fedora 32 release announcement so it would be very important to me to try to get it fixed or to otherwise help understand what the problem is so we can change the source material so that the currently used version of antora works.

Thanks for any help!

Welp, I spent maybe an hour playing with this and my conclusion is the sources are haunted. I have no idea what causes it to freak like this. However, the good news is that merging the two included files into one fixes it, so that's what I did: https://github.com/coreos/fedora-coreos-docs/pull/66

Thanks @pbokoc. I just merged the PR so let's see if it works now!

Can we re-use this ticket for gaining some sanity around our Dockerfile situation? It seems a bit incorrect that

A) We have two different dockerfiles in our repo
B) we use antora from dockerhub in build.sh

We should probably be using the same build configuration (i.e. the resulting image from a built Dockerfile) everywhere, right?

Fine with me. However the Dockerfile problem isn't something I can really help with; we'll need @asamalik to chime in.

Thanks @pbokoc for fixing this!

@dustymabe I totally agree with you, that wasn't really intentional, it just happened over time. I wish I'd have more time for this, but I took a note to clean that up and make them all use the same configuration based on a Fedora image. Thanks for pointing that out!

This seems fixed. Please let us know if there's anything further to do here...

Metadata Update from @kevin:
- Issue close_status updated to: Fixed
- Issue status updated to: Closed (was: Open)
Metadata
None

websites-general

None
None
Normal
Static archive. pagure.io was sunset in 2026; this is a read-only snapshot.
Red Hat Logo

Fedora is sponsored by Red Hat. Learn more about the relationship between Red Hat and Fedora »

© Red Hat, Inc. and others.