Activate documentation on new Antora site

[ysb33r]

When the new Antora-based documentation becomes available, it will might be necessary to make some changes to the current infrastructure. The latter has been implemented in #303 and pushes all documentation to antora-pages branch.

[mojavelinux]

We're on the home stretch to getting the new docs.asciidoctor.org site up and running. Where do we need to point to pull in the docs for the Gradle plugin?

[ysb33r]

antora_pages branch

[mojavelinux]

But I don't see any antora.yml files.

[ysb33r]

I;ll fix this on the weekend. I think there has been a bunch of changes to Antora since I did the original work.

[ysb33r]

@mojavelinux Do you want one directory per version or one tag per version?

[mojavelinux]

Doesn't matter. Antora can take it however you give it. Though I don't recommend tags. They are not a good fit for documentation. If it's generated, then one branch probably works fine.

antora.yml has always been required, so maybe it just got missed.

[abelsromero]

Any help required? A part from the missing file, the rest of projects are keeping docs in the same code branch under "docs" directory. Would it make sense to migrate the "current/latest" to it? I'd probably need to rename the current "docs" gradle project to something else though if we agree on this.

[abelsromero]

I discussed with @ysb33r and I'll be taking care of this keeping current structure in development-3.x branch branch 👍 It will take me some time first to understand how this works.

As important point, we want to keep non-release builds to gh-pages In that way the docs can be verified for development work.

[abelsromero]

I think we should reconsider how the docs are being structured and build now. I found the following problems:

• Docs are still oriented to generate a single file using asciidoctor: pages start at section 2, no nav files, attributes file being included.
• The current structure does not match Antora's model. Seeing the history, this is normal since the branch was created when the antora modules structure was not final.
• (The real issue for me) The way we are treating it in antora-pages each version would need to be treated as a module which is iirc not the proper way.

For that, and given we already have a branch for major versions, I would propose to:

1. Define which versions we want publish. We can still have pre-release if necessary pointing to the main branch (I assume that is for current development).
2. Restructure docs according to Antora expected structure. For now, seeing https://asciidoctor.github.io/asciidoctor-gradle-plugin/master/user-guide/ we would need ROOT with welcome page, plugin-configuration with most of the pages and appendices. Changes in the pages should be minimal. The most of the work will be in the nav and seeting up the antora.yml with attributes, which tbh is not much either.
3. Remove push-documentation.yml pipeline and gh-pages publication since it won't be necessary. The docs.asciidoctor.org configuration can pull from the branches directly given all will share the expected structure.

Second step would need to be replicated in the desired branches. An issue I see is that with a branch per major, we can only publish docs for most up to date minor/patch. We just addopted a branch per minor as discussed in https://github.com/asciidoctor/docs.asciidoctor.org/pull/64, but that's for leads if this project to decide.

Alternatively, we could try to keep the current model as much as possible to avoid the effor required to "antorize" each branch, but the "1 module for each version" seems a huge problem to me. Happy to be corrected.

[abelsromero]

First "crude" re-structuring

There are still details to work, but here is it the WIP branch https://github.com/abelsromero/asciidoctor-gradle-plugin/tree/issue-433-antora-migration

[abelsromero]

I take from lack of feedback, we can proceed with the proposal I presented.

To reiterate:

• It will imply changing files in branches, one branch at a time.
• Remove the docs pipelines now in place, which means, no single doc file will be available as they are now.

[ysb33r]

Go for it.

[mojavelinux]

An issue I see is that with a branch per major, we can only publish docs for most up to date minor/patch. We just addopted a branch per minor, but that's for leads if this project to decide.

I want to share an idea that could help here. Although I had said that I recommend against using tags for docs*, that's primarily applicable to active release branches. Once a release branch has settled, and activity on it becomes infrequent, that's when you could consider switching to pulling the docs from a tag. Antora allows you to source from both branches and tags. So just something to consider.

* The reason I don't recommend using tags for active release branches is because it requires making a new software release to update the documentation...which just doesn't make a lot of sense, especially for open source projects.

[abelsromero]

PR for branch development-3.x is open for review. I've called that version 3.x-dev but I am open to suggestions. When we are set, I can start work on maintenance-2.x, that should be named as 2.4.0.

[ysb33r]

An issue I see is that with a branch per major, we can only publish docs for most up to date minor/patch. We just addopted a branch per minor, but that's for leads if this project to decide.

I want to share an idea that could help here. Although I had said that I recommend against using tags for docs*, that's primarily applicable to active release branches. Once a release branch has settled, and activity on it becomes infrequent, that's when you could consider switching to pulling the docs from a tag. Antora allows you to source from both branches and tags. So just something to consider.

• The reason I don't recommend using tags for active release branches is because it requires making a new software release to update the documentation...which just doesn't make a lot of sense, especially for open source projects.

@mojavelinux What I have found to work well in some projects is to push the final Antora sources to an orphan branch, which then get tagged with the version. i.e. antora_v1.0.0. The documentation project then pulls off these tags to publish the docs for the various versions. If we release say a v1.1.1, we delete the v1.1.0 tag, so that our docs will show v1.0.0, v1.1.1. In that way we only show the docs from the latest patch release from a major-minor combination.

[mojavelinux]

You can certainly do it that way (there's no right and wrong approach here). But in practice, I have found that pulling docs from a tag for anything that is still actively maintained is an unworkable strategy for the documentation team. The documentation team then gets caught up in software release cycles, often resulting in not being able to make the docs change when they need to make it. Again, I'm not saying it can't work. But in my experience, it hasn't worked well in practice.

[abelsromero]

I am re-taking this. Just to get it going I am going to push respective docs directories to branches development-4.x with a "per branch" approach (I will remove any reference to old v3). When validated and ready I understand that needs to go to master for release, which is the one that we will use for https://docs.asciidoctor.org.

"per branch" works best IMO because it's the same one we use for other repos simplifying mental load :sweat_smile:

[mojavelinux]

I look forward to it! It will be great to have the Gradle plugin docs alongside the docs for the rest of the ecosystem and for them to be searchable. If you need any assistance, don't hesitate to reach out.