-
Notifications
You must be signed in to change notification settings - Fork 120
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Move plugin documentation to gh-pages #102
Comments
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. |
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:
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. |
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. |
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 |
@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:
FInally, do we want to keep copies of docs for past releases or only for the latest release? |
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).
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). |
@mojavelinux The issue that I see is code snippets that are extracted (using |
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. |
Challenge accepted. Let's do this. |
@mojavelinux Any chance you can create PR which just lays out the appriopriate Antorra structure in I shouldd be able to take it from there. |
I've got some time this weekend that I can dedicated to getting you started. |
- Full PDF example added to compatibility tests
- Full PDF example added to compatibility tests
- Full PDF example added to compatibility tests
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. |
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
…ciidoctor#303) Kudos to @jezhiggins & @ralph-mcardell for tips on simplifying the proxy gradlew.bat file.
As hinted in #98
The text was updated successfully, but these errors were encountered: