Hi all,
I recently jumped back into looking at docs, and took me quite a while to figure everything out, and just wondering if we could change things up a bit. follows are the things that i found confusing:
1. https://pagure.io/fedora-docs/docs-fp-o default branch is master, that hasnt been updated for two years -- should we make the default branch prod? (also the stage branch's readme still refers to https://pagure.io/fedora-docs/fedora-docs-web)
2. https://pagure.io/fedora-docs/fedora-docs-web still looks active, but it doesnt seem to be used anymore -- you don't need to push built results there, anymore right? Should this repo just be deleted, since it only ever housed built stuff anyway?
3. It took me ages to find where the static front pages were -- i finally found them at https://pagure.io/fedora-docs/pages/ but we really should update the docs docs with this information
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 https://pagure.io/fedora-docs/fedora-docs-ui start doing numbered releases of these bundles, and hosting the built zips on gitlab or pagure, and pulling from there rather than fedorapeople?
cheers, ryanlerch
On Thu, Dec 9, 2021 at 5:24 AM Ryan Lerch rlerch@redhat.com wrote:
- https://pagure.io/fedora-docs/docs-fp-o default branch is master, that hasnt been updated for two years -- should we make the default branch prod? (also the stage branch's readme still refers to https://pagure.io/fedora-docs/fedora-docs-web)
I'd be in favor of that. The "master" branch only exists to tell people not to use it which...doesn't seem all that helpful.
- https://pagure.io/fedora-docs/fedora-docs-web still looks active, but it doesnt seem to be used anymore -- you don't need to push built results there, anymore right? Should this repo just be deleted, since it only ever housed built stuff anyway?
Looks like it can be removed. The last commit to the prod branch was two years ago. Unless there's a trapdoor there that only Adam knows about.
- It took me ages to find where the static front pages were -- i finally found them at https://pagure.io/fedora-docs/pages/ but we really should update the docs docs with this information
+1
- 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 https://pagure.io/fedora-docs/fedora-docs-ui start doing numbered releases of these bundles, and hosting the built zips on gitlab or pagure, and pulling from there rather than fedorapeople?
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.
On Thu, Dec 09, 2021 at 10:23:40AM -0000, Ryan Lerch wrote:
- It took me ages to find where the static front pages were -- i finally
found them at https://pagure.io/fedora-docs/pages/ but we really should update the docs docs with this information
_Should_ the static front page be done differently, or could it _also_ be an antora doc?
On Thu, Dec 9, 2021 at 11:37 AM Matthew Miller mattdm@fedoraproject.org wrote:
_Should_ the static front page be done differently, or could it _also_ be an antora doc?
It could, but I think it would end up being an antora doc in name only. Asciidoc doesn't really have a good way to do the layout like we have on the front page (unless we get really silly with tables, which is bad for responsiveness). So we'd end up with the same content as embedded HTML.
On Thu, Dec 09, 2021 at 11:46:51AM -0500, Ben Cotton wrote:
_Should_ the static front page be done differently, or could it _also_ be an antora doc?
It could, but I think it would end up being an antora doc in name only. Asciidoc doesn't really have a good way to do the layout like we have on the front page (unless we get really silly with tables, which is bad for responsiveness). So we'd end up with the same content as embedded HTML.
I guess there are two parts to this:
1. Using the same tooling would make it more consistent, even if we're not using it to its full potential.
2. Are we fond of the front page layout?
On Thu, Dec 9, 2021 at 11:54 AM Matthew Miller mattdm@fedoraproject.org wrote:
- Using the same tooling would make it more consistent, even if we're not using it to its full potential.
Yes, but given how simple the front page is, I'm not sure the consistency makes much difference here.
- Are we fond of the front page layout?
That's the better question. I don't know that I'm particularly fond of it as-is, but I'm more fond of its current state compared how it would look in a fully-asciidoc setup. So we should look at this the other way around: let's redesign the front page, if necessary, and then put it in whatever technical implementation fits.
Ben Cotton bcotton@redhat.com wrote: ...
- Are we fond of the front page layout?
That's the better question. I don't know that I'm particularly fond of it as-is, but I'm more fond of its current state compared how it would look in a fully-asciidoc setup. So we should look at this the other way around: let's redesign the front page, if necessary, and then put it in whatever technical implementation fits.
I'd be interested in helping out with the design of the front page, and have a few preliminary thoughts there.
Allan
On Thu, Dec 9, 2021 at 11:54 AM Matthew Miller <mattdm(a)fedoraproject.org> wrote:
Yes, but given how simple the front page is, I'm not sure the consistency makes much difference here.
That's the better question. I don't know that I'm particularly fond of it as-is, but I'm more fond of its current state compared how it would look in a fully-asciidoc setup. So we should look at this the other way around: let's redesign the front page, if necessary, and then put it in whatever technical implementation fits.
Yeah, we have some limitiations because of the Antora choice -- it doesnt seem to allow you to have a hierarchy of (what is calls components) -- the most complicated structure for an antora setup i could find was these docs:
https://docs.asciidoctor.org/epub3-converter/latest/
With the list of porducts (ie components down the side)
This limitation is why we have essentially a static front page, manually updated, right?
cheers, ryanlerch
I think we can accomplish basically anything we can imagine for site navigation, if we abandon trying to have the UI bundle be a "theme" that can be applied to an arbitrary Antora site. (*)
If we merge the UI bundle into the docs-fp-org repository, then we, can, e.g., when we add a new component, add it into a tree-organized navigation menu.
There would be a bit of complexity in keeping it possible to build the components standalone with Fedora theming, but it's entirely manageable.
Regards, Owen
(*) this is not really true for the Fedora UI bundle anyways ... it expects certain things to be provided by the scripts in the docs-fp-org repository.
docs@lists.stg.fedoraproject.org
-
Allan Day -
Ben Cotton -
Matthew Miller -
Owen Taylor -
Ryan Lerch