[ https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17186063#comment-17186063 ]
Rahul Singh commented on CASSANDRA-16066: ----------------------------------------- Great! Looking forward to the POC. Where does the actual build of the docs happen. e.g. Will someone pull down cassandra-website and do edits/previews, or will they pull down cassandra .. I see that the dockerfile right now is in the main cassandra repo. > Update and rework cassandra-website material to work with Antora > ---------------------------------------------------------------- > > Key: CASSANDRA-16066 > URL: https://issues.apache.org/jira/browse/CASSANDRA-16066 > Project: Cassandra > Issue Type: Task > Components: Documentation/Website > Reporter: Anthony Grasso > Priority: Normal > > *We want to modernise the way the website is built* > Rework the cassandra-website repository to generate a UI bundle containing > resources that Antora will use when generating the Cassandra documents and > website. > *The existing method is starting to become dated* > The documentation and website templates are currently in markdown format. > Sphinx is used to generate the Cassandra documentation and Jekyll generates > the website content. One of the major issues with the existing website > tooling is that the live preview server (render site as it is being updated) > is really slow. There is a preview server that is really fast, however it is > unable to detect changes to the content and render automatically. > *We are migrating the docs to be rendered with Antora* > The work in CASSANDRA-16029 is converting the document templates to AsciiDoc > format. Sphinx is being replaced by Antora to generate the documentation > content. This change has two advantages: > * More flexibility if the Apache Cassandra documentation look and feel needs > to be updated or redesigned. > * More modern look and feel to the documentation. > *We can use Antora to generate the website as well* > Antora could also be used to generate the Cassandra website content. As > suggested on the [mailing > list|https://www.mail-archive.com/dev@cassandra.apache.org/msg15577.html] > this would require the existing markdown templates to be converted to > AsciiDoc as well. > *Antora needs a UI bundle to style content* > For Antora to generate the document content and potentially the website > content it requires a UI bundle (ui-bundle.zip). The UI bundle contains the > HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and > (site-wide) images. As such, it provides both the visual theme and user > interactions for the documentation. Effectively the UI bundle is the > templates and styling that are applied to the documentation and website > content. > *The [cassandra-website|https://github.com/apache/cassandra-website] > repository can be used to generate the UI bundle* > All the resources associated with templating and styling the documentation > and website can be placed in the > [cassandra-website|https://github.com/apache/cassandra-website] repository. > In this case the repository would serve two purposes; > * Generation of the UI bundle resources. > * Serve the production website content. > *The [cassandra|https://github.com/apache/cassandra] repository would contain > the site material* > All other material that is used to generate documentation, blogs and project > information would live in the [cassandra|https://github.com/apache/cassandra] > repository. In this case Antora would run on the > [cassandra/doc|https://github.com/apache/cassandra/doc] directory and pull in > a UI bundle released on the GitHub > [cassandra-website|https://github.com/apache/cassandra-website] repository. > The content generated by Antora would be placed in the > [cassandra-website/content|https://github.com/apache/cassandra-website/content] > directory > *Design, content, and layout would remain the same* > This proposal means the roles of each repository will change. In addition, > the workflow to publish material will change as well. However, the website > design, content, and layout will remain the same. > As an added bonus the tooling would allow for a live preview server that is > fast and responsive. However, the time to build and generate the {{nodetool}} > and Cassandra YAML AssciDoc files will still take in the order of minutes to > complete. > *The [cassandra-website|https://github.com/apache/cassandra-website] > repository would need to be modified* > The following changes would need to be made to the > [cassandra-website|https://github.com/apache/cassandra-website] repository: > ||File/Directory||Action||Reason|| > |[content/|https://github.com/apache/cassandra-website/content]|keep|Production > site content served from this directory| > |[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