Uploaded image for project: 'Cassandra'
  1. Cassandra
  2. CASSANDRA-16029

Create better Apache Cassandra 4.0 docs

Agile BoardAttach filesAttach ScreenshotBulk Copy AttachmentsBulk Move AttachmentsVotersWatch issueWatchersCreate sub-taskConvert to sub-taskMoveLinkCloneLabelsUpdate Comment AuthorReplace String in CommentUpdate Comment VisibilityDelete Comments


    • Improvement
    • Status: Resolved
    • Normal
    • Resolution: Done
    • 4.0.1
    • Documentation/Website
    • None
    • Performance
    • Challenging
    • All
    • None


      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
      • 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:

      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).



          This comment will be Viewable by All Users Viewable by All Users


            polandll Lorina Poland Assign to me
            polandll Lorina Poland
            Lorina Poland
            Jon Haddad, mck2
            0 Vote for this issue
            6 Start watching this issue




                Issue deployment