Current state of fedora docs ui bundle

Project Discussion
1

While we were working on getting our docs ready for antora 3.0, we found out that we needed a little update on the ui-bundle to get everything nice and working.
If you are able to, It would be nice if I could get some reviews about this PR#55: use display_version instead of version for component - fedora-docs/fedora-docs-ui - Pagure.io

Now, I see there is a lot of PR piling up in this repo, and it doesn’t feels like it’s actively maintained and/or monitored. I’m kind of worried that my PR stay in this limbo for a while :worried:

I’ve some concerns about how this ui-bundle is currently used in our build pipeline, which @ryanlerch and @bcotton also shared in the list not too long ago. I’m copy/pasting it so we can maybe continue this discussion here :

Ryan Lerch wrote:
4. Finally, the antora UI bundle – it seems the UI bundle is being pulled from a zip on asalalik’s fedora people – and then we are adding additional changes via supplemental-ui in the docs-fp-o repo. Is there any reason we cannot merge these changes back into Overview - fedora-docs/fedora-docs-ui - Pagure.io start doing numbered releases of these bundles, and hosting the built zips on gitlab or pagure, and pulling from there rather than fedorapeople?

Ben Coton wrote:
I’m not sure on that, but I’d like to see something like that. I don’t
want us to be dependent on a single person’s account because that’s
bad for the group and also for the person who has to carry the burden.
If there’s some technical reason we can’t host the bundles on Pagure,
we should at least have a group on fedorapeople that it pulls from so
that we can have multiple access. But a version-controlled and tagged
bundle would be best. Adam is the person who can shed light on any
technical restrictions here.

AFAIK I don’t see any technical reason that would prevent us to use, let’s say, the release repo from pagure or gitlab to host this bundle, instead of relying on a single person fedorapeople space.
We can even use gitlab-ci now to automatically build this bundle, and keep, at least, 2 separate versions for prod & staging.
That will allow us to really use the staging environment as a preview for development, without risking the production one.

Speaking of preview, this bundle is based on a (very) old version of antora default UI and would really benefit from an update, or at least on the tooling required to build & preview your changes (which doesn’t seems to work for quite some time now by looking at open issues).

Anyway, it seems like this repo needs some love, and if no one wants to, I’m willing to help and try to get this part moving.

5 Likes
2

Thanks, @darknao! I commented on the pull request. I agree that this is in a tenuous state. The reason PRs have sat untouched is that it was basically @asamalik’s and the knowledge hasn’t been spread well enough (plus there’s not currently an active docs group, more of a loose collection of people who do some work on it — more on that next week! — so I don’t think anyone felt empowered to make decisions about it.)

For the reasons in my parenthetical above, I say go for it. If something breaks, that’s what revision history is for. :slight_smile:

3

Thanks for merging the PR :slight_smile:
We still need to get the ui-bundle updated on asamalik’s space, and I guess only he can do that.
Would it be possible to get some rights on the fedora-docs-ui repo (on pagure and/or gitlab) so I can put there an updated version of the bundle that we can use, and start working on PRs?
Additionally, rights on docs-fp-o repo would also be nice :sweat_smile: That would allow me to keep the staging environment up to date, and try this new bundle on it.

If everything goes well, we may be able to deploy antora 3.0 before 2.3 become EOL next month :wink:

4

Welcome to the docs group in Pagure! That should give you all the access you need.

1 Like
5

Well, all we really need is a place where we can put the bundle and access to it so we can update it when needed. Right now it’s on Adam’s fedorapeople space, but we can point each repo to another location easily, it’s just one line in site.yml. It doesn’t even require Adam’s involvement, the problem is finding a good place.

Actually, now that I think of it… the bundle doesn’t need to be writeable by Antora, so we could just keep the packaged zip inside the UI repo and link to the file in all configs. That would fix the access problem since it would be based on the UI repo’s permissions. What do you think? Obviously keeping a zip file in a git repo isn’t ideal but I don’t think it’s a huge problem.

6

I’ve moved the bundle to the releases space of pagure, which seems the perfect place to me for this kind of artifacts.
Anyone with write access to the repo can easily upload a new package.
Those releases are then available here.

This release mechanism is also available on Gitlab.

Additionally, each bundle (or release) is linked to a version tag in this repo, so we know exactly what’s inside, and can roll back easily if we ever need to.

Both prod & staging are currently using this new bundle without issue.

2 Likes
7

I started updating the docs-ui bundle toward the upstream project, and one of the most significant changes is the automatic table of content for article, shown on the side.

image
image1384×799 240 KB

I found it quite nice, especially for long articles. What do you think? Should we push that to prod?
You can try it on our staging environment if you’d like.

2 Likes
8

I agree with that very much! I have this feature, which we also have in the wiki, already missed for our server documentation very much. I would now only need to know how to use it. We need docs. :slight_smile: I would like to start with it right away.

As I see it we are at least resolving one of long outstanding issues, #6 opened 4 years ago. Thanks a lot.

Speaking of long outstanding issues (w/o wanting to highjack this thread):

There is #36 about doc author’s credit and #67 and #128 about info inside a doc about creation / last update date. Both are very essential for doc quality.

While you’re at it, could you address that as well? :blush: That would be a great step forward.

We already include such a note in our Fedora Server documentation (example), not necessarily nice, but we haven’t found a better way.

9

You don’t need to do anything actually, it’s enabled by default (ex for the server docs: https://docs.stg.fedoraproject.org/en-US/fedora-server/)
There is a few settings you can control using page attributes, see What’s New in Antora 3.1 :: Antora Docs.

As for other issues, I’m currently reviewing the backlog. Hopefully, I’ll be able to address some of them :wink:

10

Oh, I see I should take a more frequent and closer look at our own pages.

Thanks for your efforts.

11

Aww yes, that makes navigation on long pages so much easier! Definitely push to prod, and thanks a million for doing that!

12

I’m wondering, is there a way to keep a latest version of the bundle, so that we can point every repo there instead of having to update every repo every time there’s a new release?

1 Like
13

As far as I know, Pagure can’t, but Gitlab can.
But I’m not sure repos other than doc-fp-o really require updating the ui-bundle every time.

1 Like
14

OK, good to know.

Repos don’t generally require updates, but the difference between the old bundle on Adam’s fedorapeople space and any subsequent updates will only increase in time, potentially making local previews look way different from what gets built on docs.fp.o. If we can peg every repo’s UI bundle to the latest version, we can avoid that.

1 Like
15

I wonder if it’s possible to upload a ...-latest.tar.gz for each release to pagure that’s just a copy of the latest one? That way we always point to the same URL?

16

It’s unfortunately not possible to overwrite release artifacts in pagure.
But really, this is not an issue as this repo is going to move to gitlab soon anyway.

1 Like
17

Some updates:
The ui-bundle repository has been moved to GitLab.
There is now a CI pipeline running to automatically build the bundle archive for both prod & staging (upstream) environment.
The latest up-to-date bundle can then be fetched with the following URL:

You can use any of these two URLs in your Antora playbook (site.yml) to get the latest UI version available.

2 Likes