Restructure the repo to split team info from contributing guide #63

Open

pbokoc wants to merge 1 commit from pbokoc/team-docs:iss55 into main

pbokoc commented

2026-07-10 11:05:13 +00:00

Owner

Fixes #55

The guide is now split into 2 modules:

team-info, which contains our team information
contributing, which contains the actual contributing guide

Each has its own navfile etc. Configs have all been updates so that outwardly, everything looks like it did before (although I did shuffle the table of contents a little bit based on @pboy's suggestions in #55). The default index is now team-info/index.adoc (see antora.yml); that's the one you'll see when you build the guide - it's the original index.

I also made sure each file has an include for the attributes file and :experimental: at the top, and cleaned up the config YMLs a little bit.

Fixes #55 The guide is now split into 2 modules: * `team-info`, which contains our team information * `contributing`, which contains the actual contributing guide Each has its own navfile etc. Configs have all been updates so that outwardly, everything looks like it did before (although I did shuffle the table of contents a little bit based on @pboy's suggestions in #55). The default index is now `team-info/index.adoc` (see `antora.yml`); that's the one you'll see when you build the guide - it's the original index. I also made sure each file has an include for the attributes file and `:experimental:` at the top, and cleaned up the config YMLs a little bit.

pbokoc added 1 commit

2026-07-10 11:05:13 +00:00

55 - Restructure the repo to split team info from contributing guide 4c873782b7

pbokoc requested review from pboy

2026-07-10 11:05:24 +00:00

pbokoc changed title from ~~55 - Restructure the repo to split team info from contributing guide~~ to Restructure the repo to split team info from contributing guide

2026-07-10 11:05:56 +00:00

pboy commented

2026-07-11 04:32:19 +00:00

Owner

That's a massive work! Thanks a lot.

2 questions

If I read the PR correctly, we will not have under module a ROOT subdirectory, but instead the two "team-info" and "contributing". Is this permitted under the Antora specification? If I understand @darknao correctly (see the docs-template repository), a ROOT directory is required. Or is it just a convention?

The index page for "contributing" seems to start with "What skills do I need?" which should be the index page for the "content" section. And the content sections has currently no index.adoc. So, doesn't this page belong there?

And wouldn’t it be necessary to add an index page for ‘contributing’ as well, containing the first two sections of the existing ‘contributing’ page (as we discussed on Matrix and I summarized in ticket #56)?

That's a massive work! Thanks a lot. 2 questions 1. If I read the PR correctly, we will not have under module a ROOT subdirectory, but instead the two "team-info" and "contributing". Is this permitted under the Antora specification? If I understand @darknao correctly (see the docs-template repository), a ROOT directory is required. Or is it just a convention? 2. The index page for "contributing" seems to start with "What skills do I need?" which should be the index page for the "content" section. And the content sections has currently no index.adoc. So, doesn't this page belong there? And wouldn’t it be necessary to add an index page for ‘contributing’ as well, containing the first two sections of the existing ‘contributing’ page (as we discussed on Matrix and I summarized in ticket [#56](https://forge.fedoraproject.org/docs/tickets/issues/56))?