SPARKC-600 Refactor documentation for 3.0

[ianjevans]

Description

SPARKC-600

Converted existing Markdown files to Asciidoc. Restructured docs into Antora modules. Added workflow to generate docs using Antora and publish to GitHub Pages. Modified reference generator to output Asciidoc file.

How did the Spark Cassandra Connector Work or Not Work Before this Patch

Docs were difficult to navigate, and weren't published as a docset.

General Design of the patch

Converted and updated the docs to use Asciidoc syntax. Refactored the docs into Antora modules to make them easier to navigate, and update going forward. Added Antora configuration files to use a DataStax UI bundle to match the current look-and-feel. Added GitHub Action workflow to automatically generate and publish the docs on push to GitHub Pages.

How Has This Been Tested?

Ran local unit tests.

Checklist:

• I have a ticket in the OSS JIRA
• I have performed a self-review of my own code
• Locally all tests pass (make sure tests fail without your patch)

[jtgrabowski]

@ianjevans may I review this one?

[ianjevans]

Yes, although I am not getting the integration tests fully passing with DSE 6.7.

…

On Jun 26, 2020, at 7:00 AM, Jaroslaw Grabowski ***@***.***> wrote:  @ianjevans may I review this one? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[RussellSpitzer]

I am a bit worried about us breaking all existing links to documentation with this change. There are a large number of resources out in the world which link to the docs as is in markdown and this will change all of those links to 404's. We should probably retain those endpoints and have them link to the new relevant docs.

[ianjevans]

I am a bit worried about us breaking all existing links to documentation with this change. There are a large number of resources out in the world which link to the docs as is in markdown and this will change all of those links to 404's. We should probably retain those endpoints and have them link to the new relevant docs.

I really wish GitHub had the concept of file redirects, since this is a side-effect of using the GItHub repo web renderer. If the doc links were to e.g. GitHub Pages we could redirect to the new locations and file names, and that will hopefully be the model going forward for maintainability.

If we could figure out a solution that doesn't involve keeping all 20 of the old .md files around indefinitely, I'd vastly prefer that, but I don't have any clever ideas. Are most of the links to the quick start and e.g. connecting?

[jtgrabowski]

@ianjevans Is there a way we could leverage work that's been done here and at the same time don't break all the old .md files?