spark-cassandra-connector icon indicating copy to clipboard operation
spark-cassandra-connector copied to clipboard

Published 20 hours ago • verified publisher icon datastax

SPARKC-600 Refactor documentation for 3.0

Open ianjevans opened this issue 4 years ago • 4 comments

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:

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

ianjevans avatar Jun 18 '20 21:06 ianjevans

@ianjevans may I review this one?

jtgrabowski avatar Jun 26 '20 14:06 jtgrabowski

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 [email protected] 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.

ianjevans avatar Jun 26 '20 14:06 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?

ianjevans avatar Jul 08 '20 22:07 ianjevans

@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?

jtgrabowski avatar Aug 26 '20 12:08 jtgrabowski