As a side note, I'm working on using software already packaged for fedora to render the guidelines, and I already have a rough prototype running locally.

Would switching from antora to something available via dnf install be an acceptable solution for you, @tibbs?

My main concern is that people who wish to contribute (including us on the Committee) should be able to do so reasonably. That includes being able to see something very similar to how their contributions will appear once accepted. It should not require additional system configuration besides simply installing a relatively small set of packages.

If we can achieve that without being concerned about how docs.fedoraproject.org is actually generated, then to me that would be far less objectionable. Maybe enough to keep me from voting +1 on this proposal though I think there should still be a reasoned discussion.

It would, however, make me question what the point of Antora actually is. I assume there are things it provides which we aren't using, but having our own "local rendering" solution could then preclude us making use of those. It would certainly work as a stopgap measure until Antora is packaged, but there is no guarantee that will actually happen.

I still have objections to what appears to be the abandonment of the packaging requirement in Fedora's infrastructure as well as the general attitude that containers obviate the need for proper packaging, but I recognize that this isn't the proper forum for that.

@tibbs docs is continuing to look for someone to package antora. We do think it is important.

Would a packaged antora that we a) encourage you to run via containers and b) is installable locally for those who wish going to meet your need?. As it is nodejs I don't think we can make any promises with regards to package-count as you seem to indicate you want.

@tibbs How does this look? I've "hacked" this together today.

https://decathorpe.fedorapeople.org/

It's built from the current sources (slightly adapted), only with software already available from the fedora repos (jekyll, jekyll-asciidoc). Builds don't require containers or anything weird. Full rendering takes ~2 seconds, and incremental rebuilds for small changes are even faster.

I can push my changes to a git repo somewhere if you'd like to look at what I've changed.

Depending on tools that aren't part of Fedora doesn't seem acceptable to me either. I like the overall idea of something markdown-ish stored in Git instead of the wiki, but only if working on it is simple. A local asciidoc workflow using packages in the Fedora repos sounds much better than anything using containers.

If node.js requires the use of a container, then to me that would rule out tools based on node.js for our workflow.

Use of node.js doesn't require a container. A container was simply presented to us as the simplest way to run the software. Certainly you could simply install it from the upstream source, probably with something no more difficult than calling npm and watching it install probably a very large number of dependencies. I think it would be fair to provide those instructions, but I don't personally know what they might be.

The problem with node.js stuff is generally the astounding dependency trees things have, with version interdependencies galore. It's not unpackageable, but it isn't exactly easy to package, either. Not because node is hard to package, but because there's so much of it. It just takes time and a bit of understanding of packaging and node itself. And a whole lot of bugzilla tickets and fedpkg calls to get things reviewed and imported. (I suppose bundling could be employed to cut down on the dependency tree, but honestly I don't know what the dep tree looks like so it's hard to say.)

But do keep in mind that I've never packaged node stuff myself. I have watched reviews fly by for packages which basically contain five lines of actual javascript code plus metadata. See most of nodejs-ansi-* for some hilarious examples.

Anyway, my objection here is that this process hasn't even been started. The impression I received was that since the infrastructure team no longer has a requirement that deployed software be packaged, there was no perceived need to package it. I don't think that does a service to anyone who actually wants to contribute to the documentation.

@decathorpe: That looks similar; probably sufficiently similar to be useful. But misses the sidebar (at least for me). Since the current sidebar is seems to be somewhat broken, fixing it to make sure the tree structure of the document shows up properly there like some of the other collections under docs.fp.org should be a priority. But it doesn't seem to be something you can preview without actually running antora. (Maybe that sidebar is the value it adds? I don't know where that comes from.)

@tibbs I don't think we would be able to maintain both systems in parallel. (Or it would not be worth the effort just to get local asciidoc rendering.) It requires a different directory structure and setup (although the source files require almost no changes).

The only thing the default jekyll theme doesn't support out of the box is a sidebar - that's why I included the "Contents" page to list all the available sub-pages. It would be possible to add a sidebar, but we would have to implement it ourselves (and I am no HTML/CSS magician). But, it looks like there is extensive documentation for doing a navbar here. Side note: the current sidebar is generated from the guidelines/modules/ROOT/nav.adoc file, as far as I can tell.

I've pushed my rough "conversion" to jekyll to a fork of this repo, so you can see what I did, and maybe try if building it works better this way.

https://pagure.io/fork/decathorpe/packaging-committee/commits/wip-jekyll

I added some information about the usage (CLI commands etc.) for testing purposes here:

https://pagure.io/fork/decathorpe/packaging-committee/blob/wip-jekyll/f/README.jekyll.md

I really don't see us using this anytime soon (or at all), but at the very least, this gives us another option (and one that doesn't rely on containers with non-packaged software).

Initial work on packaging antora actually did get started, but then was stalled on a rabbit hole of doom involving a thing called nodegit which apparently bundles a forked openssl. (Can I think of worse ideas? Yes, but it'll take a few minutes.)

Good news is that upstream is aware of this and on board with making things better.
I'd really, really like to not have the documentation fragment; is "we are progressing in good faith towards a solution" acceptable?

I'm closing this because it's obvious we aren't going to go back. But I do believe we made a mistake in jumping into this so early. Not just because of the packaging issue, but also because the new pages are actually a step back from the wiki in end-user usability and because the PR thing, while convenient for some things, doesn't actually fit the workflow that we've had all that well.

I'm sure it will get worked out eventually but we should have waited until it was closer to being "there".

That's a fair criticism. Thanks @tibbs. We'll get the packaging issue sorted out. Are there tickets open for the usability issues? The Antora team is very interested in helping us make this work, so we have both upstream and Fedora Docs Team interest.