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

Update and rework cassandra-website material to work with Antora

    XMLWordPrintableJSON

    Details

    • Type: Task
    • Status: In Progress
    • Priority: Normal
    • Resolution: Unresolved
    • Fix Version/s: None
    • Component/s: Documentation/Website
    • Labels:
      None
    • Change Category:
      Operability
    • Complexity:
      Normal
    • Platform:
      All
    • Impacts:
      None

      Description

      We want to modernise the way the website is built
      Rework the cassandra-website repository to generate a UI bundle containing resources that Antora will use when generating the Cassandra documents and website.

      The existing method is starting to become dated
      The documentation and website templates are currently in markdown format. Sphinx is used to generate the Cassandra documentation and Jekyll generates the website content. One of the major issues with the existing website tooling is that the live preview server (render site as it is being updated) is really slow. There is a preview server that is really fast, however it is unable to detect changes to the content and render automatically.

      We are migrating the docs to be rendered with Antora
      The work in CASSANDRA-16029 is converting the document templates to AsciiDoc format. Sphinx is being replaced by Antora to generate the documentation content. This change has two advantages:

      • More flexibility if the Apache Cassandra documentation look and feel needs to be updated or redesigned.
      • More modern look and feel to the documentation.

      We can use Antora to generate the website as well
      Antora could also be used to generate the Cassandra website content. As suggested on the mailing list this would require the existing markdown templates to be converted to AsciiDoc as well.

      Antora needs a UI bundle to style content
      For Antora to generate the document content and potentially the website content it requires a UI bundle (ui-bundle.zip). The UI bundle contains the HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and (site-wide) images. As such, it provides both the visual theme and user interactions for the documentation. Effectively the UI bundle is the templates and styling that are applied to the documentation and website content.

      The cassandra-website repository can be used to generate the UI bundle
      All the resources associated with templating and styling the documentation and website can be placed in the cassandra-website repository. In this case the repository would serve two purposes;

      • Generation of the UI bundle resources.
      • Serve the production website content.

      The cassandra repository would contain the documentation material, while the rest of the non-versioned pages would contain that material

      • All other material that is used to generate documentation would live in the cassandra repository. In this case Antora would run on the cassandra/doc directory and pull in a UI bundle released on the GitHub cassandra-website repository. The content generated by Antora using the site.yml file located in this repo can be used to preview the docs for review.
      • All other non-versioned material, such as the blogs, development instructions, and third-party page would live in the GitHub cassandra-website repository. Antora will generate the full website using the site.yml located in this repo, using both as content sources the material located in both the cassandra and cassandra-website repositories.

      Design, content, and layout would remain the same
      This proposal means the roles of each repository will change. In addition, the workflow to publish material will change as well. However, the website design, content, and layout will remain the same.

      As an added bonus the tooling would allow for a live preview server that is fast and responsive. However, the time to build and generate the nodetool and Cassandra YAML AssciDoc files will still take in the order of minutes to complete.

      The cassandra-website repository would need to be modified
      The following changes would need to be made to the cassandra-website repository:

      File/Directory Action Reason
      content/ keep Production site content served from this directory
      src/_data/ delete site.yml and antora.yml include this info
      src/_includes/ delete Replace with UI bundle components
      src/_layout/ delete Replace with UI bundle components
      src/_plugins/ delete Replace with UI bundle components
      src/_posts/ move Convert to AsciiDoc format and place in cassandra repository
      src/_sass/ delete Replace with UI bundle components
      src/_templates/ move Convert to AsciiDoc format (template format for blog posts) and place in cassandra repository
      src/blog/ delete Replace with index.adoc that will be the initial page for blogs
      src/css/ delete Replace with UI bundle components
      src/doc/ delete Content already generated with Antora in cassandra repository
      src/icons/ keep Probably needed for site generation but might be moved to a different folder
      src/img/ keep Probably needed for site generation but might be moved to a different folder
      src/js/ delete Replace with UI bundle components
      src/Gemfile delete Replace with node modules
      src/Gemfile.lock delete Replace with node modules
      src/Makefile delete Replace build mechanism with Gulp and Docker
      src/README delete Place information and instructions in top level README
      src/_config.yml delete Replaced by site.yml
      src/apachecon_cfp.md delete?? This file is out of date
      src/community.md move Convert to AsciiDoc and place in cassandra repository
      src/download.md move Convert to AsciiDoc and place in cassandra repository
      src/index.html keep Might need to convert to AsciiDoc and place in cassandra repository
      src/robot.txt keep Needed by site
      src/third-party.md move Convert to AsciiDoc and place in cassandra repository

        Attachments

        1. image-2020-09-06-07-17-14-705.png
          110 kB
          Rahul Singh
        2. image-2020-09-05-13-24-13-606.png
          118 kB
          Rahul Singh

          Issue Links

            Activity

              People

              • Assignee:
                Anthony Grasso Anthony Grasso
                Reporter:
                Anthony Grasso Anthony Grasso
                Authors:
                Anthony Grasso
                Reviewers:
                Lorina Poland, Melissa Logan, Michael Semb Wever
              • Votes:
                0 Vote for this issue
                Watchers:
                6 Start watching this issue

                Dates

                • Created:
                  Updated: