[
https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=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/[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]
