[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[ https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17408763#comment-17408763 ] Michael Semb Wever edited comment on CASSANDRA-16066 at 9/2/21, 11:50 AM: -- Committed [370103315dc670489d99d2643e9f597638ca1c76|https://github.com/apache/cassandra-website/commit/370103315dc670489d99d2643e9f597638ca1c76] and [e833a5d60bae85fbdace1b6598155e6961de6bfd|https://github.com/apache/cassandra-website/commit/e833a5d60bae85fbdace1b6598155e6961de6bfd] and [56a532993af73f1f5ddf548cfd3da48831473d50|https://github.com/apache/cassandra-website/commit/56a532993af73f1f5ddf548cfd3da48831473d50] and [32e8c8cf27ba879c9368eb5236186f36d5d65f38|https://github.com/apache/cassandra-website/commit/32e8c8cf27ba879c9368eb5236186f36d5d65f38] and [e4e4ff182af66a86f2f931bfe632a422ca69fe7a|https://github.com/apache/cassandra-website/commit/e4e4ff182af66a86f2f931bfe632a422ca69fe7a] and [370103315dc670489d99d2643e9f597638ca1c76|https://github.com/apache/cassandra-website/commit/370103315dc670489d99d2643e9f597638ca1c76]. was (Author: michaelsembwever): Committed [|370103315dc670489d99d2643e9f597638ca1c76https://github.com/apache/cassandra-website/commit/370103315dc670489d99d2643e9f597638ca1c76] and [e833a5d60bae85fbdace1b6598155e6961de6bfd|https://github.com/apache/cassandra-website/commit/e833a5d60bae85fbdace1b6598155e6961de6bfd] and [56a532993af73f1f5ddf548cfd3da48831473d50|https://github.com/apache/cassandra-website/commit/56a532993af73f1f5ddf548cfd3da48831473d50] and [32e8c8cf27ba879c9368eb5236186f36d5d65f38|https://github.com/apache/cassandra-website/commit/32e8c8cf27ba879c9368eb5236186f36d5d65f38] and [e4e4ff182af66a86f2f931bfe632a422ca69fe7a|https://github.com/apache/cassandra-website/commit/e4e4ff182af66a86f2f931bfe632a422ca69fe7a] and [370103315dc670489d99d2643e9f597638ca1c76|https://github.com/apache/cassandra-website/commit/370103315dc670489d99d2643e9f597638ca1c76]. > Create tooling and update repository layout to render new website > - > > Key: CASSANDRA-16066 > URL: https://issues.apache.org/jira/browse/CASSANDRA-16066 > Project: Cassandra > Issue Type: Task > Components: Documentation/Website >Reporter: Anthony Grasso >Assignee: Michael Semb Wever >Priority: Normal > Labels: pull-request-available > Fix For: 3.0.26, 3.11.12, 4.0.1, 4.1 > > 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 >
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/31/21, 10:10 AM:
---
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/_/index.html
# see parent ticket for further steps required before pushing to staging
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/_/home.html
# see parent ticket for further steps required before pushing to staging
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
> Create tooling and update repository layout to render new website
> -
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
> Issue Type: Task
> Components: Documentation/Website
>Reporter: Anthony Grasso
>Assignee: Michael Semb Wever
>Priority: Normal
> Labels: pull-request-available
> 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,
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/31/21, 10:10 AM:
---
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/_/home.html
# see parent ticket for further steps required before pushing to staging
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
# see parent ticket for further steps required before pushing to staging
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
> Create tooling and update repository layout to render new website
> -
>
> Key: CASSANDRA-16066
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16066
> Project: Cassandra
> Issue Type: Task
> Components: Documentation/Website
>Reporter: Anthony Grasso
>Assignee: Michael Semb Wever
>Priority: Normal
> Labels: pull-request-available
> 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,
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/18/21, 8:38 PM:
--
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
# see parent ticket for further steps required before pushing to staging
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
> Create tooling and update repository layout to render new website
> -
>
> 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
> Labels: pull-request-available
> 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
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/18/21, 8:38 PM:
--
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -i -b cassandra:trunk,cassandra-3.11 -u
cassandra:https://github.com/polandll/cassandra.git -z
./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
> Create tooling and update repository layout to render new website
> -
>
> 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
> Labels: pull-request-available
> 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
>
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/4/21, 6:58 PM:
-
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA\-16066}} branch.
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA-16066}} branch.
> Create tooling and update repository layout to render new website
> -
>
> 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
> Labels: pull-request-available
> 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
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/4/21, 6:57 PM:
-
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
- currently the pull request contains 70 commits, many check-point and many
duplicated commits. It should only be ~6 commits, like the
{{anthony/CASSANDRA-16066}} branch.
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
> Create tooling and update repository layout to render new website
> -
>
> 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
> Labels: pull-request-available
> 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
>
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[ https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393379#comment-17393379 ] Michael Semb Wever edited comment on CASSANDRA-16066 at 8/4/21, 6:56 PM: - Pull Request: https://github.com/apache/cassandra-website/pull/68 was (Author: michaelsembwever): Pull Request: https://github.com/apache/cassandra-website/pull/67 > Create tooling and update repository layout to render new website > - > > 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 > Labels: pull-request-available > 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
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/4/21, 6:55 PM:
-
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
Otherwise +1
> Create tooling and update repository layout to render new website
> -
>
> 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
> Labels: pull-request-available
> 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.
>
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17393398#comment-17393398
]
Michael Semb Wever edited comment on CASSANDRA-16066 at 8/4/21, 6:50 PM:
-
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
Otherwise +1
was (Author: michaelsembwever):
This work is already being used to deploy to the {{asf-staging}} and
{{asf-site}} branches.
Specifying the following steps:
{code}
cd cassandra-website
git switch anthony/CASSANDRA-16066_full_history
git pull
git switch paul/new-website
git pull
git rebase anthony/CASSANDRA-16066_full_history
./run.sh website-ui bundle
./run.sh website build -z ./site-ui/build/ui-bundle.zip
open site-content/build/html/Project/home.html
{code}
Review Feedback:
- the doap.rdf file must remain (see why
[here|https://projects.apache.org/doap.html])
- the {{run.sh}} is intense. Could this have been python, or a makefile, for
the sake of encouraging contributors to it? (not a blocker)
- in {{site-content/Dockerfile}} the defaults should be
{code}
ENV ANTORA_SITE_URL="/"
ENV ANTORA_SITE_START_PAGE="_"
{code}
> Create tooling and update repository layout to render new website
> -
>
> 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
[jira] [Comment Edited] (CASSANDRA-16066) Create tooling and update repository layout to render new website
[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17326637#comment-17326637
]
Anthony Grasso edited comment on CASSANDRA-16066 at 6/26/21, 3:09 AM:
--
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|https://github.com/ossarga/cassandra-website/tree/anthony/CASSANDRA-16066].
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:java}
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:java}
$ 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:java}
$ ./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:java}
$ ./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
