[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Anthony Grasso (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17326637#comment-17326637
 ] 

Anthony Grasso commented on CASSANDRA-16066:


A near complete implementation of the new website tooling can be found on my 
cassandra-website [fork|https://github.com/ossarga/cassandra-website] on branch 
[anthony/CASSANDRA-16066_rebased|https://github.com/ossarga/cassandra-website/commits/anthony/CASSANDRA-16066_rebased].

Items left to do:
 * Complete repository README updates
 * Update CI commands and triggers

If you look through the changes on the branch above you will notice the website 
repository code is separated into two main parts. These parts are represented 
by the directories at the root level of the project. Specifically the structure 
of the repository is:

{code}
ROOT
 - site-content
 - site-ui
{code} 

h2. Site UI

The 'site-ui' directory contains only the UI styling files that determines the 
look and feel of the site. A ui-bundle.zip file containing the styling 
information will be generated from the contents of this directory. Generation 
of the ui-bundle.zip will be done using {{gulp}} launched inside a Docker 
container.

h2. Site Content

The 'site-content' directory contains all the raw page information e.g. where 
to download, developer guidelines, how to commit patches, etc. The live website 
HTML is generated from the contents of this directory. Generation of the HTML 
content is done by {{antora}} launched inside a Docker container. As part of 
the website HTML generation, the _ui-bundle.zip_ file, and the Cassandra 
documentation location are passed to {{antora}}. It uses the ui-bundle.zip to 
style the website. The Cassandra documentation location will be used to gather 
and generate documentation for each Cassandra version.

h1. Developer Examples

The development cycle is very similar to the existing website development 
cycle. As such, to test changes before committing, it is a requirement that you 
build the website locally. Building the Apache Cassandra website takes a number 
of steps. To make things easier we have provided a suite of tools to build the 
full website in a few simple commands and have it ready to commit via git.

h2. Tooling components

The tooling is made up of the following components

* Run script: {{./run.sh}} - Provides a single command line interface that 
generates the docker commands to run the website and UI docker containers. 
Using the containers, it can build the Cassandra website UI components, 
generate the Cassandra versioned documentation, and generate the website HTML.
* Website Docker container: {{Dockerfile}} and {{docker-entrypoint.sh}} - 
Contains the libraries necessary to generate the Cassandra versioned 
documentation, and generate the website HTML using Antora.
* Antora Site YAML script: {{bin/site_yaml_generator.py}} - Used by the Website 
Docker container to create the YAML file that defines the sources for the 
website content, optionally the cassandra versioned documentation, and the UI 
styling bundle to apply.
* Website UI Docker container: {{site-ui/Dockerfile}} and 
{{site-ui/docker-entrypoint.sh}} - Contains the libraries necessary to generate 
the UI bundle ZIP file the is applied by Antora to style the website and 
documentation.

h2. Building Prerequisites

To build and run the Docker container you will need {{Docker}} version 2.0.0.0 
or greater. If you need a copy of the site code you will need {{git}} as well.

h2. Building the Website

If you need a copy of the site code run this command:

{code}
$ git clone https://github.com/apache/cassandra-website.git
$ cd ./cassandra-website
{code}

To build the website only, run the following command from within the 
{{./cassandra-website}} directory (assuming you used the above clone command).

{code}
$ ./run.sh website build
{code}

*Tip:* In order to prevent root-owned modified files in your repository, the 
container user, {{build}}, is set up with a default {{UID=1000:GID=1000}}, 
which is usually the first user configured on a linux machine. If your local 
user is different you should set up the container user with your local host 
user's UID:GID, replace the above with:

{code}
$ ./run.sh -v UID_ARG=$(id -u) -v GID_ARG=$(id -g) website container
$ ./run.sh website build
{code}

This will build the website content using your local copy of the 
cassandra-website, and the current checked-out branch. Use this command if you 
want to make a change to a top-level webpage without building the docs for any 
versions of cassandra.

Once building has completed, the HTML content will be in the 
{{./site-content/build/html/}} directory ready to be reviewed and committed.

h2. Build the Website when Developing

The website tooling is very flexible and allows for a wide range of development 
scenarios.

h3. Build the website from a different branch

You can tell the website 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Anthony Grasso (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17281041#comment-17281041
 ] 

Anthony Grasso commented on CASSANDRA-16066:


The majority of proposed changes are now complete and are on [my 
fork|https://github.com/ossarga/cassandra-website] of the cassandra-website on 
branch 
[anthony/CASSANDRA-16066|https://github.com/ossarga/cassandra-website/tree/anthony/CASSANDRA-16066].

Items left to do:

* Complete wrapper script that simplifies the usage of the new tooling 
(currently in progress and about 75% complete).
* Update CI commands and triggers.
* Update repository README.

The bulk of the work is done and reviews of the proposed changes can probably 
start.

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Assignee: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] and 
> [cassandra-website|https://github.com/apache/cassandra-website] 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Anthony Grasso (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17225840#comment-17225840
 ] 

Anthony Grasso commented on CASSANDRA-16066:


I've started prototyping what tooling would look like for the cassandra-website 
repository if it used Anotra. What I've done so far can be found on [my 
fork|https://github.com/ossarga/cassandra-website] of the cassandra-website on 
a branch called 
[anthony/CASSANDRA-16066|https://github.com/ossarga/cassandra-website/tree/anthony/CASSANDRA-16066].

At the time of writing it addresses the following points in the previous 
comment:
 * Tooling can generate entire website including in-tree docs
 * Address legalities of conflicting licenses (unable to store Antora's UI 
bundle and generation in-tree).
 * Generated content is never committed to the master branch of the 
cassandra-website (relevant to Cassandra releases).
 * Continue to maintain staging branch and live branch in cassandra-website.

Todo items:
 * Push to cassandra-website staging branch.
 * Preview mode for (in-tree) docs when editing.
 * Preview mode for when editing UI components.
 * Cassandra website CI only tiggers if there are changes in the website 
repository or when Cassandra in-tree docs change (can be made to listen changes 
in multiple repositories).
 * Ability to generate in-tree docs without using Antora so it can be bundled 
in with a Cassandra release (Simple AsciiDoc build as a starting point).

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Anthony Grasso (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17193632#comment-17193632
 ] 

Anthony Grasso commented on CASSANDRA-16066:


[~mck] and I have had a chat to summarise what we think the goals are for the 
tooling of the website and in-tree docs. What we came up with so far is as 
follows.

Goals immediate and long term:
 * Tooling can generate entire website including in-tree docs and push to 
{{cassandra-website}} staging branch.
 * Tooling provides a preview mode for (in-tree) docs when editing.
 * Address legalities of conflicting licenses (unable to store Antora's UI 
bundle and generation in-tree).
 * Generated content is never committed to the master branch of the 
{{cassandra-website}} (relevant to Cassandra releases).
 * Continue to maintain staging branch and live branch in {{cassandra-website}}.
 * Cassandra website CI only tiggers if there are changes in the website 
repository or when Cassandra in-tree docs change (can be made to listen changes 
in multiple repositories).
 * Ability to generate in-tree docs without using Antora so it can be bundled 
in with a Cassandra release (Simple AsciiDoc build as a starting point).

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/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, 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17192803#comment-17192803
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

Thanks [~polandll]

I think we all understand that your proposal – the issue that [~mck] had was 
not on the workflow per se, but the artifacts related to Antora in the 
cassandra repository which is distributed. 

 

_I will just make the point that the reason we were building a docker container 
that "runs" antora in cassandra was to facilitate a writer/developer building a 
preview of the docs they are changing. We want to make it as easy as possible 
for a contributor to check whether the doc change they propose will build 
correctly._

+*I think this is a great goal.*+ While a use is able to preview / edit docs in 
the cassandra repo, there will still need to be a way to generate in-tree docs. 
For this specific need, [~mck] 's concern was about Antora's licensing. 

_Also, please understand that there are only yaml files for antora located in 
the cassandra repo (site.yml for the preview build and antora.yml for the docs 
source)._

+*We are all on the same page here.*+  

_Lastly, the cassandra-website antora yaml files will build the whole site, 
docs and non-docs pages. It will use the cassandra repo as one content source 
(for the docs), and the cassandra-website repo as a second content source (for 
the non-docs). Docs will not be built in the cassandra repo then moved, but 
rather that repo will be sourced to build the docs as the website is built._

Acknowledged. +*We are all on the same page here as well.*+ We weren't 
suggesting that it would. This is reflected in the diagram already.. all *site* 
related doc generation is done in the cassandra-website repository using both a 
local cassandra-website src and a remote cassandra/docs src.

 
_I think your diagram is not in agreement with what I just described. But I've 
just had my first chance to try and digest this long convo._
 
Understood, but the goal of the diagram is not to represent your proposal but 
to mitigate the licensing issue that [~mck] brought. It is not a critique on 
your proposal, but rather a potential compromise to
 # standardize the docs / site via asciidoc format (current proposal)
 # generate nice looking sites + docs with antora (current proposal)
 # have a license-conflict-free way to generate docs that get distributed with 
the binaries using the same asciidoc format with an alternate tool that doesn't 
have licensing restrictions for distributed artifacts. (additional suggestion 
to current proposal) 

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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. 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Lorina Poland (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17192605#comment-17192605
 ] 

Lorina Poland commented on CASSANDRA-16066:
---

I'll let [~Anthony Grasso] answer, since I'm sort of on vacation right now. 

I will just make the point that the reason we were building a docker container 
that "runs" antora in cassandra was to facilitate a writer/developer building a 
preview of the docs they are changing. We want to make it as easy as possible 
for a contributor to check whether the doc change they propose will build 
correctly.

Also, please understand that there are only yaml files for antora located in 
the cassandra repo (site.yml for the preview build and antora.yml for the docs 
source).

Lastly, the cassandra-website antora yaml files will build the whole site, docs 
and non-docs pages. It will use the cassandra repo as one content source (for 
the docs), and the cassandra-website repo as a second content source (for the 
non-docs). Docs will not be built in the cassandra repo then moved, but rather 
that repo will be sourced to build the docs as the website is built.

I think your diagram is not in agreement with what I just described. But I've 
just had my first chance to try and digest this long convo.

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora using the site.yml file located in this repo 
> can be 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Michael Semb Wever (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17191274#comment-17191274
 ] 

Michael Semb Wever commented on CASSANDRA-16066:


The diagram looks great now [~xingh]. Hopefully [~polandll], [~Anthony Grasso], 
something like this is feasible ??

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] and 
> [cassandra-website|https://github.com/apache/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 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17191242#comment-17191242
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

Acknowledged [~mck] I've updated the diagram. Thanks for the Jira issue related 
to the Antora licensing. This was helpful.

 With Antora we can keep the UI bundle *and anything to do with antora* only in 
cassandra-website. Even though Antora can be used to generate the / and /docs 
section of the website and push to asf-staging, it shouldn't need to be a 
requirement to generate docs in the release. As mentioned earlier, this can be 
achieved with other tools for a basic doc conversion from Asciidoc to HTML or 
PDF. e.g. Asciidoctor uses MIT License.  We will need to ensure that our 
Asciidocs are managed in a way that is conducive to both *Antora* and something 
like *Asciidoctor* . (Any non-conflicting licensed tool can be used .. as 
mentioned before.)

 
{noformat}
Permission is hereby granted, free of charge, to any person obtaining a copy of 
this software and associated documentation files (the "Software"), to deal in 
the Software without restriction, including without limitation the rights to 
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
of the Software, and to permit persons to whom the Software is furnished to do 
so, subject to the following conditions:
{noformat}
 

!image-2020-09-06-07-17-14-705.png!

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png, 
> image-2020-09-06-07-17-14-705.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Michael Semb Wever (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17191131#comment-17191131
 ] 

Michael Semb Wever commented on CASSANDRA-16066:


WIth the diagram above, currently we are not generating docs to the asf-site 
branch. The asf-site branch is just a manual copy (`git reset …`) of 
asf-staging after it has been manually verified on cassandra.staged.a.o. See 
the bottom of the 
[README.md|https://github.com/apache/cassandra-website/blob/master/README.md].

Antora uses the MPL (Mozilla Public License). The Antora UI bundle involves 
original or modified files from Antora under this license. Such a UI bundle is 
usually put into the git repository. Having such a bundle in the 
cassandra-website repository is ok, because we never release or distribute it. 
Having the bundle in the cassandra repository is in itself not a problem but we 
would have to change the release process to ensure it does not appear in either 
the source *-src.tar.gz or binary *-bin.tar.gz release artefacts. Like you say 
[~xingh], it would just be easier if the UI bundle was kept out of the 
cassandra repository, and any docs available inside release artefacts not be 
built with antora.

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/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 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17191118#comment-17191118
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

Lorina's proposal above mentions a docker container in the cassandra src to 
generate documentation as well in the cassandra-website src. 

If the Antora license constraint prevents us from placing Antora artifacts in 
the cassandra.git, does it still count if the actual build process is 100% done 
by a prebuilt docker image ? If so, then what you ask

 [~mck] based on what you mentioned about Antora license, does this mean it 
prevents us from even having a Dockerfile that mentions an Antora image + 
configuration yml which tells which files to convert?

*"For the releases, can the in-tree asciidocs be built without antora and 
solely in-tree?*

If we can't have Antora what-so-ever  on the cassandra.git, then we can use a 
much more basic asciidoc to html/pdf generator which doesn't have such 
constraints. There are plenty out there and some of them may just be a HTML/JS 
shell that renders Asciidoc to HTML dynamically without the need for a 
generation step for intree docs. 
([https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d,] 

At the same time, Antora being run in the cassandra-website repo would pull the 
same asciidoc files and create nice looking site out of it. 

 

!image-2020-09-05-13-24-13-606.png!

 

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
> Attachments: image-2020-09-05-13-24-13-606.png
>
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17191037#comment-17191037
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

Thanks for clarifying the antora license constraint. I like your approach 
because it achieves the same thing with two build processes that run within the 
cassandra-website : 1 to update / from contents in the website repo and 2 to 
update /docs/ from the cassandra repo. 

I'll review the links again and circle back but I think what you are saying is 
possible. Antora can do local, remote public or remote private repos. The only 
change from [~polandll] 's plan is to make sure we only run Antora in the 
cassandra-website source for both sets of artifacts. 

 

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] and 
> [cassandra-website|https://github.com/apache/cassandra-website] repositories.
> *Design, content, and layout would remain the same*
>  This proposal means the roles of each 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Michael Semb Wever (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17191016#comment-17191016
 ] 

Michael Semb Wever commented on CASSANDRA-16066:


{quote}*I propose this (or this is what the intention may have been all along)*

* build process for cassandra
** uses docs/dockerfile as needed on releases to include in release
** uses docs/dockerfile as needed on releases to publish only /docs/ section of 
the site ( separate public path to push docs content to)
* build process for cassandra-website
** uses /dockerfile as needed on publish blog/ etc. to / section of the site ( 
separate public path to push site content to)
{quote}


Some questions.

bq. uses docs/dockerfile as needed on releases to publish only /docs/ 

Only one website can serve the contents. A build action in the 
cassadra-repository would then have to push commit (on the asf-staging branch) 
into the cassandra-website repository? 

bq. uses docs/dockerfile as needed on releases to include in release

It would be nice to have better bundled docs. But keep in mind that the Antora 
has an incompatible license and none of its files (original or modified) can be 
put into a C* release artefact.


It would be nice avoiding cross-repository dependencies. 
For the releases, can the in-tree asciidocs be built without antora and solely 
in-tree? This would solve bundling the docs into the release and simplify the 
release process (by not being dependent on the cassandra-website repository). 
If this is not possible I suggest we remove all docs from the release bundles 
(like it is today).

For the website staging updates…
- when there's an update to cassandra-website, can we have one build command to 
update just its contents on the asf-staging branch?
 - when there's an update to cassandra, can we have one build command (in 
cassandra-website) that updates just the versioned docs (/docs//) 
contents on the asf-staging branch?

More information on how the docs get published is in
- https://infra.apache.org/project-site.html
- 
https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features#git.asf.yamlfeatures-Specifyingasub-directorytopublishto

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/cassandra-website] 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17190746#comment-17190746
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

>From my understanding, this is what I think lorina is suggesting. 

 
 * cassandra / docs / intree docs - have a dockerfile so that the the asciidocs 
can be used to create artifacts related just for documentation. 
 * cassandra-website - have a docker file so that the asciidocs can be used to 
create artifacts just for the site 

 

both of them will refer to the same ui package (referenced in git)
 * When a release is cut, the in tree build process would generate HTML/PDF 
whatever to be tarred up (we should make a "lite" version without the docs) 
with the .tar.gz
 * when the website is published, the website build process would build the 
static site content and may need to rely on the dockerfile from cassandra.git 
to produce a full website release**

*I propose this (or this is what the intention may have been all along)*
 * build process for cassandra
 ** uses docs/dockerfile as needed on releases to include in release
 ** uses docs/dockerfile as needed on releases to *publish* only /docs/ section 
of the site ( separate public path to push docs content to)
 * build process for cassandra-website
 ** uses /dockerfile as needed on *publish* blog/ etc. to / section of the site 
( separate public path to push site content to)

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora using the 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Michael Semb Wever (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17190317#comment-17190317
 ] 

Michael Semb Wever commented on CASSANDRA-16066:


Second what [~rustyrazorblade] says. No content (AFAIK) should be moved from 
the cassandra-website to the cassandra git repository. In fact the opposite, 
there is a number of pages that exist in the cassandra git repository that are 
not "versioned" and should be moved to the cassandra-website repository.

Keep in mind the different ways of generating the in-tree docs, and where they 
are used (I suspect there are no used anymore, i.e. the half-hearted and 
limited docs we bundle into a release, but it needs to be checked).

If the "web resources" are all in the cassandra-website repository, and only 
versioned content in-tree, is there any need to have any build actions (or 
docker image) in the cassandra repository at all?

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository. In this case 
> Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] and 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Lorina Poland (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17186068#comment-17186068
 ] 

Lorina Poland commented on CASSANDRA-16066:
---

The plan is to have two slightly different Docker containers, one in 
cassandra/doc that can be used to build the docs for preview while doing 
documentation work, and one in cassandra-website that would build the docs 
along with the other files, with preview and production build options. So, the 
overlap is similar, but the site.yml on cassandra-website would include all 
content sources, whereas cassandra/doc would only include the docs content 
sources. Here's an example of part of the site.yml file:
{code:java}
content:
  sources:
  - url: https://github.com/polandll/cassandra.git
branches:
- 'doc_redo_asciidoc' // this is the equivalent of trunk (4.0)
- 'doc_redo_asciidoc3.11' // this is the equivalent of cassandra3.11
start_path: doc/source
  - url: https://github.com/polandll/cassandra-website.git
branches:
- test_new_doc_builder
start_path: source
{code}
The second content source listed here will only be included the site.yml file 
on cassandra-website. 

Please note that I've been doing testing, so I do have both in cassandra/doc at 
the moment on my working branch, but that will change. 

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository would contain 
> the site material*
>  All other material that is used to generate documentation, blogs and project 
> information would live in the [cassandra|https://github.com/apache/cassandra] 
> repository. In this case Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora would be placed in the 
> [cassandra-website/content|https://github.com/apache/cassandra-website/content]
>  directory
> *Design, content, and layout would remain 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17186063#comment-17186063
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

Great! Looking forward to the POC. Where does the actual build of the docs 
happen. e.g. Will someone pull down cassandra-website and do edits/previews, or 
will they pull down cassandra .. I see that the dockerfile right now is in the 
main cassandra repo. 

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository would contain 
> the site material*
>  All other material that is used to generate documentation, blogs and project 
> information would live in the [cassandra|https://github.com/apache/cassandra] 
> repository. In this case Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora would be placed in the 
> [cassandra-website/content|https://github.com/apache/cassandra-website/content]
>  directory
> *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|https://github.com/apache/cassandra-website] 
> repository would need to be modified*
>  The following changes would need to be made to the 
> [cassandra-website|https://github.com/apache/cassandra-website] repository:
> ||File/Directory||Action||Reason||
> |[content/|https://github.com/apache/cassandra-website/content]|keep|Production
>  site content served from this directory|
> 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Lorina Poland (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17186032#comment-17186032
 ] 

Lorina Poland commented on CASSANDRA-16066:
---

Antora can build different styling "templates" for various pages. It can also 
use multiple repos for the content to be built. For instance, the non-doc pages 
can be stored in the cassandra-website repo and styled as, for instance, blog 
posts or non-doc pages. The docs, meanwhile, live in the cassandra/doc repo and 
are built with doc styling. 

Antora is quite versatile for the UI.

I've already started converting the cassandra-website pages to adoc (md->adoc 
is simple), and added the blog posts and code development information to that, 
along with the Community, Download, 3rd party, Contact Us, C* plug-ins, 
glossary, and native protocol specs (v.3,4,5).

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository would contain 
> the site material*
>  All other material that is used to generate documentation, blogs and project 
> information would live in the [cassandra|https://github.com/apache/cassandra] 
> repository. In this case Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora would be placed in the 
> [cassandra-website/content|https://github.com/apache/cassandra-website/content]
>  directory
> *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 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Rahul Singh (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17182177#comment-17182177
 ] 

Rahul Singh commented on CASSANDRA-16066:
-

I agree. I think SSGs are great. I use Hugo and Gatsby and have gotten used to 
Jekyll. Antora seems to be purpose built for documentation w/ TOCs etc. 

I’d recommend keeping the “marketing” / landing pages as @Jon mentioned 
separate and maybe in the future using something that is more focused on 
content rather than documentation  that makes it appealing and easy to add / 
edit content. 

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository would contain 
> the site material*
>  All other material that is used to generate documentation, blogs and project 
> information would live in the [cassandra|https://github.com/apache/cassandra] 
> repository. In this case Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora would be placed in the 
> [cassandra-website/content|https://github.com/apache/cassandra-website/content]
>  directory
> *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|https://github.com/apache/cassandra-website] 
> repository would need to be modified*
>  The following changes would need to be made to the 
> [cassandra-website|https://github.com/apache/cassandra-website] repository:
> ||File/Directory||Action||Reason||
> 

[jira] [Commented] (CASSANDRA-16066) Update and rework cassandra-website material to work with Antora

[Jon Haddad (Jira)]

[ 
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17182070#comment-17182070
 ] 

Jon Haddad commented on CASSANDRA-16066:


I recommend keeping the blog out of the C* repo as it isn't version specific, 
and we don't need multiple copies of the same blog.  Same with the community 
page, download page, and anything else that isn't tied to a version.

> Update and rework cassandra-website material to work with Antora
> 
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
>  Issue Type: Task
>  Components: Documentation/Website
>Reporter: Anthony Grasso
>Priority: Normal
>
> *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|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] 
> 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|https://github.com/apache/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|https://github.com/apache/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|https://github.com/apache/cassandra] repository would contain 
> the site material*
>  All other material that is used to generate documentation, blogs and project 
> information would live in the [cassandra|https://github.com/apache/cassandra] 
> repository. In this case Antora would run on the 
> [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in 
> a UI bundle released on the GitHub 
> [cassandra-website|https://github.com/apache/cassandra-website] repository. 
> The content generated by Antora would be placed in the 
> [cassandra-website/content|https://github.com/apache/cassandra-website/content]
>  directory
> *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|https://github.com/apache/cassandra-website] 
> repository would need to be modified*
>  The following changes would need to be made to the 
> [cassandra-website|https://github.com/apache/cassandra-website] repository:
> ||File/Directory||Action||Reason||
> |[content/|https://github.com/apache/cassandra-website/content]|keep|Production
>  site content served from this directory|
>