[ https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=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 > 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: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org