Bug: Create better Apache Cassandra 4.0 docs
Status: Resolved
Priority: Normal
Resolution: Done
Created: 05/Aug/20 20:09
Resolved: 24/Jun/21 22:28

The proof of concept to create new Documentation showed that a combination of the static site generator (SSG) Antora + Asciidoc files would provide the most flexibility in redesigning the Apache C* OSS pages.

Current proof of concept: [https://polandll.github.io/site/Cassandra/4.0/]

To update the docs, the tools to write needed an update, too, to provide a better UX and modern look and feel. The old tools (reStructured Text, Sphinx) will be replaced with the new tools ([AsciiDoc|http://asciidoc.org/], [Antora|http://antora.org/]). 

See the attachments for screenshots of the current docs and the POC docs.

The advantages of asciidoc+antora:
 * Rich markdown language that is directly editable.
 * Good organizational structure for docs files
 * Flexible build/publishing capabilities, including content from multiple repositories and branches
 * Flexible web UI, built separately from the doc files and static site.
 * JS extensions that enable additional functionality.

To complete the conversion, the following steps are required:
 * Pandoc used for conversion of rSt files to adoc files
 ** Followed by significant manual editing to fix the errors left over after conversion
 * Creation of new antora files (site.yml, antora.yml, CSS and layout)
 ** Integration with plug-ins (lunr for search, tabs for additional codeblock capabilities)
 ** Finish the UI to match current Apache C* UI, or engage designer to do a new design
 *** Put the ASF pulldown in the main header banner, like Apache Spark does ([https://spark.apache.org/downloads.html])
 * Modification of build scripts to work with Antora
 ** Modification of python scripts that generation YAML and nodetool docs
 *** Make sure that these scripts are run for each version
 ** Modification of cassandra/doc Makefile 
 ** Dockerfile and docker-entrypoint.sh files to use Docker for documentation build
 * Modification of cassandra-website to work with Antora
 ** Dockerfile and docker-entrypoint.sh files to use Docker for documentation build
 * Figure out how to handle older versions that are not converted to asciidoc now
 ** Put in TBD? Copy 4.0 branch with note to rewrite later?
 * Figure out why tabs-block antora extension is working locally but not in GH pages (may or may not be important)

Other tasks:
 * Complete conversion, plus editing the current docs before Apache C* 4.0 GA
 * Further improvements for docs organization 
 ** [https://docs.google.com/document/d/1aeNtgyPAsKcNa0GSKvl2ywlFEj30714ry4Sb5turWeE/edit?usp=sharing]
 ** Get some sections out of Docs, like Developing Code info -> Community
 * Solve the issue of CQL highlighting/lexer/parser issue
 ** Need CQL to be submitted to pygments
 * Addition of more useful documentation - tutorials, how-to guides, separate reference guide

Current work: [https://github.com/polandll/cassandra/blob/doc_redo_asciidoc/|https://github.com/polandll/cassandra/blob/doc_redo_asciidoc/doc/Dockerfile]

 Relevant Links:

Original source for antora-ui: [https://gitlab.com/antora/antora-ui-default]

(Mozilla public license 2.0)

Current working repo for antora-ui: [https://github.com/ianjevans/antora-ui-datastax]  in oss branch

Lunr search implemented with:  [https://github.com/Mogztter/antora-lunr] and [https://github.com/Mogztter/antora-site-generator-lunr]

(MIT license)

Codeblock tabs implemented with: Dan Allen's tabs-block.js code (finding source).