Move plugin documentation to gh-pages

[aalmiray]

As hinted in #98

[mojavelinux]

Here's some research we did on reworking the documentation pipeline so that it also integrates with the asciidoctor.org website. There's a lot of work to be done to make it happen, but every journey begins with a small step.

asciidoctor/asciidoctor-documentation-planning#7

[mojavelinux]

I'd like to have this hosted under the main asciidoctor.org site. There will be two locations for each project. For this project, those locations are:

• /docs/asciidoctor-gradle-plugin (and perhaps an alias, /docs/gradle-plugin)
• /projects/asciidoctor-gradle-plugin (and perhaps an alias, /projects/gradle-plugin)

The first is for the docs, obviously. The second is part of a dashboard similar to code.facebook.com/projects and engineering.twitter.com/opensource/projects.

[ysb33r]

I am kickstarting this. With 2.0 the documentation is getting so vast that we cannot effetcively use a single README anymore. So @mojavelinux we are going to need your input in how we can build asciidoctor-gradle docuemtnation and then push it it to the main Asciidoctor site as part of the build.

[mojavelinux]

The Asciidoctor documentation is moving to Antora. That means all you need to do is set up an Antora component structure in this repository and Antora will be able to consume it. It's probably best to look at what Asciidoctor.js is doing to learn how to get that set up.

https://github.com/asciidoctor/asciidoctor.js/tree/master/docs

[ysb33r]

@mojavelinux What I think at this point is to create a docs folder which will be the source for the docs. But for the build, I think two things should happen:

• Build locally, so that the docs can be viewed easily
• Copy (& commit) docs and appropriate source to a detached/orphaned branch in github, which can then be accessed via Antorra.

FInally, do we want to keep copies of docs for past releases or only for the latest release?

[mojavelinux]

I would not recommend using a generated file structure. The docs should just live in a folder just like any other source files. Antora will then accesses them where they live. We don't want to over-complicate this.

You can still build the files locally with or without Antora. The pages are just regular AsciiDoc files. The only thing you might need to build them without Antora is an extension to handle Antora's xrefs. But that's something we'll want to start thinking about for the Gradle plugin anyway.

There's also the possibility of using Antora directly from Gradle to build the files locally. You could have the Gradle build generate a playbook file dynamically for the current branch, then feed it to Antora. I'd certainly encourage experimentation in this area. (You can find an Antora plugin for Gradle under developmpent here: https://github.com/rwinch/antora-gradle-plugin).

do we want to keep copies of docs for past releases or only for the latest release?

Just leave the docs in the git reference that corresponds to the software release (whether that's a branch or a tag). Then we can decide which docs to include in the site.

The model Asciidoctor core is going to use is to have any version (down to the minor version level) that is still supported. Once the version becomes unsupported, the docs will stop being published (but still available in the source repo).

[ysb33r]

I would not recommend using a generated file structure. The docs should just live in a folder just like any other source files. Antora will then accesses them where they live. We don't want to over-complicate this.

@mojavelinux The issue that I see is code snippets that are extracted (using tag::foo[]) for real code. If Antorra pulls the repo remotely, how does this work?

[mojavelinux]

Antora will be able to aggregate code from outside an Antora structure (see https://gitlab.com/antora/antora/issues/195). It just doesn't yet. But we shouldn't put our efforts in workarounds. Instead, we should plan for the capability being there. This gives us an opportunity to study a real world scenario.

[ysb33r]

But we shouldn't put our efforts in workarounds. Instead, we should plan for the capability being there. This gives us an opportunity to study a real world scenario.

Challenge accepted.

Let's do this.

[ysb33r]

@mojavelinux Any chance you can create PR which just lays out the appriopriate Antorra structure in docs subfolder?

I shouldd be able to take it from there.

[mojavelinux]

I've got some time this weekend that I can dedicated to getting you started.

[ysb33r]

Collapsing this work in #303 because there is a huge overlap and I would like SNAPSHOT docs to be pushed to gh-pages so that reviews can take place before final release to the new Antora-based website. Also because we still have some delays on the latter, this could serve a s a temporary documentation website.