Migrate docs to Antora site

[abelsromero]

As mentioned in asciidoctor/asciidoctor.org#977, actions have begun for the new site current pre-release in https://asciidoctor-docs.netlify.app/asciidoctor/2.0/.

I finished migration of the maven-plugin docs (open for review asciidoctor/asciidoctor-maven-plugin#498), so if there're no objection I will start work here too.

Given the Asciidoctor site is scheduled to release soon I'll only focus on docs, no gh-pages.

[mojavelinux]

Given the Asciidoctor site is scheduled to release soon I'll only focus on docs, no gh-pages.

👍 Indeed. We're working as hard as possible for it to go live in a week or two.

[abelsromero]

First approach for the toc.
I think we can have 2 modules:

• ROOT: with most of the documentation.
• project: with support and operations docs.

Unless stated, each bullet will be a page.
I have reordered a couple of elements and moved the integrators guide into the main "flow", but my intent is to keep the content mostly as is it now.

// == ROOT module

* Distribution
// Moved here to aggregate installation as dependency and as CLI (sdkman, choco)
* Installation
* Command line interface
// Moved content from Integrator's guide here
* Converting documents
** Integrate AsciidoctorJ: Convert documents via the API
*** First steps: Converting a document
*** The Asciidoctor interface
*** Safe mode and file system access
*** Conversion options
** Ruby runtime

// This feels disconnected: move to 'Help & guides' ?
* Locating files
* Reading the document tree

* Extend AsciidoctorJ: Write your own extensions

* Extensions
** Conversion process overview
** Understanding the AST classes
** Writing an extension
*** Block Macro Processors
*** Inline Macro Processors
*** Block Processors
*** Include Processors
*** Preprocessors
*** Postprocessors
*** Treeprocessors
*** Docinfo Processors
** Registering extensions
*** Manually registering extensions with javaExtensionRegistry
*** Bulk extension registration (aka. extension groups)
*** Automatically loading extensions
// previously titled 'Publish everywhere: Adapt Asciidoctor to your own target format'

* Writing a converter

// previously titled 'Syntax Highlighter API'
* Writing a Syntax Highlighter API
** Implement a syntax highlighter adapter
** Lifecycle of a SyntaxHighlighterAdapter
** Formatting the source block element
** Link and copy external resources
** Static syntax highlighting during conversion
** Invocation order
** Automatically loading syntax highlighters

// Single page
* Logs handling
** API
** SPI

// REMOVE EPUB· docs
// * Converting to EPUB3

// Split extension-migration-guide.adoc
* Help & Guides
** Migrating from AsciidoctorJ 1.6.x to 2.0.x
** Migrating from AsciidoctorJ 1.5.x to 1.6.x
// Following sections moved from README
** Accessing the JRuby instance
** GEM_PATH
** Using AsciidoctorJ in an OSGi environment
** Optimization
** Running AsciidoctorJ on WildFly
** Using a pre-release version
** Using a snapshot version

//== PROJECT module

// Moved to `project` module
** Development
*** Project layout
*** Build the project
*** Develop in an IDE
**** IntelliJ IDEA
**** Eclipse
*** Continuous integration
*** Publish the artifacts
*** Publish snapshot versions
// Move text of 'Resources' to Contributing section
// * Resources

[robertpanzer]

Looks good!

Minor comments:

• Maybe ** Ruby runtime can go under ** Integrate AsciidoctorJ: Convert documents via the API?
• * Locating files: Yes, this is indeed somehow disconnected and not even part of the API. We might even drop it completely and consider it as an implementation detail of the CLI
• Reading the document tree Maybe that would fit into "Understanding the AST classes" having a small example showing how to get the AST from an Asciidoc source file?
• Logs: Maybe move this into the Integrate AsciidoctorJ: Convert documents via the API part? It somehow is the way to get access to errors and warnings created by Asciidoctor.

[abelsromero]

2 comments on the 2nd and 3rd points:

* `* Locating files`: Yes, this is indeed somehow disconnected and not even part of the API. We might even drop it completely and consider it as an implementation detail of the CLI

OK to remove for now, but...
I never considered them as internal, more of a "nice utils". At least that's how the maven-plugin uses it. What I don't understand why they are under jruby package when DirectoryWalker interface and implementations do not deppend on implementation. Maybe we should rethink them, promote them to it's own package in v3 and then document the whole hierarchy of interface + classes.

* `Reading the document tree` Maybe that would fit into "Understanding the AST classes" having a small example showing how to get the AST from an Asciidoc source file?

I had the same though, but the section is about the Asciidoctor.load and Asciidoctor.loadFile methods. And it makes sense to be adjacent to Converting documents because these are the two main methods of the interface.
Maybe another case for help and guides? With a title like "Document processing withot conversion" ?