[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Lorina Poland updated CASSANDRA-16066:
--------------------------------------
Description:
*We want to modernise the way the website is built*
Rework the cassandra-website repository to generate a UI bundle containing
resources that Antora will use when generating the Cassandra documents and
website.
*The existing method is starting to become dated*
The documentation and website templates are currently in markdown format.
Sphinx is used to generate the Cassandra documentation and Jekyll generates the
website content. One of the major issues with the existing website tooling is
that the live preview server (render site as it is being updated) is really
slow. There is a preview server that is really fast, however it is unable to
detect changes to the content and render automatically.
*We are migrating the docs to be rendered with Antora*
The work in CASSANDRA-16029 is converting the document templates to AsciiDoc
format. Sphinx is being replaced by Antora to generate the documentation
content. This change has two advantages:
* More flexibility if the Apache Cassandra documentation look and feel needs
to be updated or redesigned.
* More modern look and feel to the documentation.
*We can use Antora to generate the website as well*
Antora could also be used to generate the Cassandra website content. As
suggested on the [mailing
list|https://www.mail-archive.com/[email protected]/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 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|
|[src/_data/|https://github.com/apache/cassandra-website/src/_data]|delete|_site.yml_
and _antora.yml_ include this info|
|[src/_includes/|https://github.com/apache/cassandra-website/src/_includes]|delete|Replace
with UI bundle components|
|[src/_layout/|https://github.com/apache/cassandra-website/src/_layout]|delete|Replace
with UI bundle components|
|[src/_plugins/|https://github.com/apache/cassandra-website/src/_plugins]|delete|Replace
with UI bundle components|
|[src/_posts/|https://github.com/apache/cassandra-website/src/_posts]|move|Convert
to AsciiDoc format and place in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/_sass/|https://github.com/apache/cassandra-website/src/_sass]|delete|Replace
with UI bundle components|
|[src/_templates/|https://github.com/apache/cassandra-website/src/_templates]|move|Convert
to AsciiDoc format (template format for blog posts) and place in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/blog/|https://github.com/apache/cassandra-website/src/blog]|delete|Replace
with _index.adoc_ that will be the initial page for blogs|
|[src/css/|https://github.com/apache/cassandra-website/src/css]|delete|Replace
with UI bundle components|
|[src/doc/|https://github.com/apache/cassandra-website/src/doc]|delete|Content
already generated with Antora in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/icons/|https://github.com/apache/cassandra-website/src/icons]|keep|Probably
needed for site generation but might be moved to a different folder|
|[src/img/|https://github.com/apache/cassandra-website/src/img]|keep|Probably
needed for site generation but might be moved to a different folder|
|[src/js/|https://github.com/apache/cassandra-website/src/js/]|delete|Replace
with UI bundle components|
|[src/Gemfile|https://github.com/apache/cassandra-website/src/Gemfile]|delete|Replace
with node modules|
|[src/Gemfile.lock|https://github.com/apache/cassandra-website/src/Gemfile.lock]|delete|Replace
with node modules|
|[src/Makefile|https://github.com/apache/cassandra-website/src/Makefile]|delete|Replace
build mechanism with Gulp and Docker|
|[src/README|https://github.com/apache/cassandra-website/src/README]|delete|Place
information and instructions in top level README|
|[src/_config.yml|https://github.com/apache/cassandra-website/src/_config.yml]|delete|Replaced
by _site.yml_|
|[src/apachecon_cfp.md|https://github.com/apache/cassandra-website/src/apachecon_cfp.md]|delete??|This
file is out of date|
|[src/community.md|https://github.com/apache/cassandra-website/src/community.md]|move|Convert
to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
repository|
|[src/download.md|https://github.com/apache/cassandra-website/src/download.md]|move|Convert
to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
repository|
|[src/index.html|https://github.com/apache/cassandra-website/src/index.html]|keep|Might
need to convert to AsciiDoc and place in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/robot.txt|https://github.com/apache/cassandra-website/src/robot.txt]|keep|Needed
by site|
|[src/third-party.md|https://github.com/apache/cassandra-website/src/third-party.md]|move|Convert
to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
repository|
was:
*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/[email protected]/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|
|[src/_data/|https://github.com/apache/cassandra-website/src/_data]|delete|_site.yml_
and _antora.yml_ include this info|
|[src/_includes/|https://github.com/apache/cassandra-website/src/_includes]|delete|Replace
with UI bundle components|
|[src/_layout/|https://github.com/apache/cassandra-website/src/_layout]|delete|Replace
with UI bundle components|
|[src/_plugins/|https://github.com/apache/cassandra-website/src/_plugins]|delete|Replace
with UI bundle components|
|[src/_posts/|https://github.com/apache/cassandra-website/src/_posts]|move|Convert
to AsciiDoc format and place in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/_sass/|https://github.com/apache/cassandra-website/src/_sass]|delete|Replace
with UI bundle components|
|[src/_templates/|https://github.com/apache/cassandra-website/src/_templates]|move|Convert
to AsciiDoc format (template format for blog posts) and place in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/blog/|https://github.com/apache/cassandra-website/src/blog]|delete|Replace
with _index.adoc_ that will be the initial page for blogs|
|[src/css/|https://github.com/apache/cassandra-website/src/css]|delete|Replace
with UI bundle components|
|[src/doc/|https://github.com/apache/cassandra-website/src/doc]|delete|Content
already generated with Antora in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/icons/|https://github.com/apache/cassandra-website/src/icons]|keep|Probably
needed for site generation but might be moved to a different folder|
|[src/img/|https://github.com/apache/cassandra-website/src/img]|keep|Probably
needed for site generation but might be moved to a different folder|
|[src/js/|https://github.com/apache/cassandra-website/src/js/]|delete|Replace
with UI bundle components|
|[src/Gemfile|https://github.com/apache/cassandra-website/src/Gemfile]|delete|Replace
with node modules|
|[src/Gemfile.lock|https://github.com/apache/cassandra-website/src/Gemfile.lock]|delete|Replace
with node modules|
|[src/Makefile|https://github.com/apache/cassandra-website/src/Makefile]|delete|Replace
build mechanism with Gulp and Docker|
|[src/README|https://github.com/apache/cassandra-website/src/README]|delete|Place
information and instructions in top level README|
|[src/_config.yml|https://github.com/apache/cassandra-website/src/_config.yml]|delete|Replaced
by _site.yml_|
|[src/apachecon_cfp.md|https://github.com/apache/cassandra-website/src/apachecon_cfp.md]|delete??|This
file is out of date|
|[src/community.md|https://github.com/apache/cassandra-website/src/community.md]|move|Convert
to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
repository|
|[src/download.md|https://github.com/apache/cassandra-website/src/download.md]|move|Convert
to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
repository|
|[src/index.html|https://github.com/apache/cassandra-website/src/index.html]|keep|Might
need to convert to AsciiDoc and place in
[cassandra|https://github.com/apache/cassandra] repository|
|[src/robot.txt|https://github.com/apache/cassandra-website/src/robot.txt]|keep|Needed
by site|
|[src/third-party.md|https://github.com/apache/cassandra-website/src/third-party.md]|move|Convert
to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
repository|
> 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/[email protected]/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 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|
> |[src/_data/|https://github.com/apache/cassandra-website/src/_data]|delete|_site.yml_
> and _antora.yml_ include this info|
> |[src/_includes/|https://github.com/apache/cassandra-website/src/_includes]|delete|Replace
> with UI bundle components|
> |[src/_layout/|https://github.com/apache/cassandra-website/src/_layout]|delete|Replace
> with UI bundle components|
> |[src/_plugins/|https://github.com/apache/cassandra-website/src/_plugins]|delete|Replace
> with UI bundle components|
> |[src/_posts/|https://github.com/apache/cassandra-website/src/_posts]|move|Convert
> to AsciiDoc format and place in
> [cassandra|https://github.com/apache/cassandra] repository|
> |[src/_sass/|https://github.com/apache/cassandra-website/src/_sass]|delete|Replace
> with UI bundle components|
> |[src/_templates/|https://github.com/apache/cassandra-website/src/_templates]|move|Convert
> to AsciiDoc format (template format for blog posts) and place in
> [cassandra|https://github.com/apache/cassandra] repository|
> |[src/blog/|https://github.com/apache/cassandra-website/src/blog]|delete|Replace
> with _index.adoc_ that will be the initial page for blogs|
> |[src/css/|https://github.com/apache/cassandra-website/src/css]|delete|Replace
> with UI bundle components|
> |[src/doc/|https://github.com/apache/cassandra-website/src/doc]|delete|Content
> already generated with Antora in
> [cassandra|https://github.com/apache/cassandra] repository|
> |[src/icons/|https://github.com/apache/cassandra-website/src/icons]|keep|Probably
> needed for site generation but might be moved to a different folder|
> |[src/img/|https://github.com/apache/cassandra-website/src/img]|keep|Probably
> needed for site generation but might be moved to a different folder|
> |[src/js/|https://github.com/apache/cassandra-website/src/js/]|delete|Replace
> with UI bundle components|
> |[src/Gemfile|https://github.com/apache/cassandra-website/src/Gemfile]|delete|Replace
> with node modules|
> |[src/Gemfile.lock|https://github.com/apache/cassandra-website/src/Gemfile.lock]|delete|Replace
> with node modules|
> |[src/Makefile|https://github.com/apache/cassandra-website/src/Makefile]|delete|Replace
> build mechanism with Gulp and Docker|
> |[src/README|https://github.com/apache/cassandra-website/src/README]|delete|Place
> information and instructions in top level README|
> |[src/_config.yml|https://github.com/apache/cassandra-website/src/_config.yml]|delete|Replaced
> by _site.yml_|
> |[src/apachecon_cfp.md|https://github.com/apache/cassandra-website/src/apachecon_cfp.md]|delete??|This
> file is out of date|
> |[src/community.md|https://github.com/apache/cassandra-website/src/community.md]|move|Convert
> to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
> repository|
> |[src/download.md|https://github.com/apache/cassandra-website/src/download.md]|move|Convert
> to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
> repository|
> |[src/index.html|https://github.com/apache/cassandra-website/src/index.html]|keep|Might
> need to convert to AsciiDoc and place in
> [cassandra|https://github.com/apache/cassandra] repository|
> |[src/robot.txt|https://github.com/apache/cassandra-website/src/robot.txt]|keep|Needed
> by site|
> |[src/third-party.md|https://github.com/apache/cassandra-website/src/third-party.md]|move|Convert
> to AsciiDoc and place in [cassandra|https://github.com/apache/cassandra]
> repository|
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
