[ https://issues.apache.org/jira/browse/CASSANDRA-16066?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17191118#comment-17191118 ]
Rahul Singh commented on CASSANDRA-16066: ----------------------------------------- Lorina's proposal above mentions a docker container in the cassandra src to generate documentation as well in the cassandra-website src. If the Antora license constraint prevents us from placing Antora artifacts in the cassandra.git, does it still count if the actual build process is 100% done by a prebuilt docker image ? If so, then what you ask [~mck] based on what you mentioned about Antora license, does this mean it prevents us from even having a Dockerfile that mentions an Antora image + configuration yml which tells which files to convert? *"For the releases, can the in-tree asciidocs be built without antora and solely in-tree?* If we can't have Antora what-so-ever on the cassandra.git, then we can use a much more basic asciidoc to html/pdf generator which doesn't have such constraints. There are plenty out there and some of them may just be a HTML/JS shell that renders Asciidoc to HTML dynamically without the need for a generation step for intree docs. ([https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d,] At the same time, Antora being run in the cassandra-website repo would pull the same asciidoc files and create nice looking site out of it. !image-2020-09-05-13-24-13-606.png! > 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 > Attachments: image-2020-09-05-13-24-13-606.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