Details
-
Improvement
-
Status: Resolved
-
Normal
-
Resolution: Done
-
None
-
Performance
-
Challenging
-
All
-
None
Description
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, Antora).
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 python scripts that generation YAML and nodetool docs
- 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/
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).
