You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by "Lorina Poland (Jira)" <ji...@apache.org> on 2020/08/07 15:34:00 UTC
[jira] [Updated] (CASSANDRA-16029) Create better Apache Cassandra
4.0 docs
[ https://issues.apache.org/jira/browse/CASSANDRA-16029?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Lorina Poland updated CASSANDRA-16029:
--------------------------------------
Change Category: Performance
Complexity: Challenging
Fix Version/s: 4.0
Reviewers: Jon Haddad, Mick Semb Wever
Status: Open (was: Triage Needed)
> Create better Apache Cassandra 4.0 docs
> ---------------------------------------
>
> Key: CASSANDRA-16029
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16029
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation/Website
> Reporter: Lorina Poland
> Assignee: Lorina Poland
> Priority: Normal
> Fix For: 4.0
>
> Attachments: CurrentDocs.png, NewImprovedDocs.png
>
>
> The proof of concept to create new Documentation showed that a combination of the static site generator (SSG) Antora + Asciidoc files would provide the most flexibility in redesigning the Apache C* OSS pages.
> Current proof of concept: [https://polandll.github.io/site/Cassandra/4.0/]
> To update the docs, the tools to write needed an update, too, to provide a better UX and modern look and feel. The old tools (reStructured Text, Sphinx) will be replaced with the new tools ([AsciiDoc|http://asciidoc.org], [Antora|http://antora.org]).
> See the attachments for screenshots of the current docs and the POC docs.
> The advantages of asciidoc+antora:
> * Rich markdown language that is directly editable.
> * Good organizational structure for docs files
> * Flexible build/publishing capabilities, including content from multiple repositories and branches
> * Flexible web UI, built separately from the doc files and static site.
> * JS extensions that enable additional functionality.
> To complete the conversion, the following steps are required:
> * Pandoc used for conversion of rSt files to adoc files
> ** Followed by significant manual editing to fix the errors left over after conversion
> * Creation of new antora files (site.yml, antora.yml, CSS and layout)
> ** Integration with plug-ins (lunr for search, tabs for additional codeblock capabilities)
> ** Finish the UI to match current Apache C* UI, or engage designer to do a new design
> *** Put the ASF pulldown in the main header banner, like Apache Spark does ([https://spark.apache.org/downloads.html])
> * Modification of build scripts to work with Antora
> ** Modification of python scripts that generation YAML and nodetool docs
> *** Make sure that these scripts are run for each version
> ** Modification of cassandra/doc Makefile
> ** Dockerfile and docker-entrypoint.sh files to use Docker for documentation build
> * Modification of cassandra-website to work with Antora
> ** Dockerfile and docker-entrypoint.sh files to use Docker for documentation build
> * Figure out how to handle older versions that are not converted to asciidoc now
> ** Put in TBD? Copy 4.0 branch with note to rewrite later?
> * Figure out why tabs-block antora extension is working locally but not in GH pages (may or may not be important)
> Other tasks:
> * Complete conversion, plus editing the current docs before Apache C* 4.0 GA
> * Further improvements for docs organization
> ** [https://docs.google.com/document/d/1aeNtgyPAsKcNa0GSKvl2ywlFEj30714ry4Sb5turWeE/edit?usp=sharing]
> ** Get some sections out of Docs, like Developing Code info -> Community
> * Solve the issue of CQL highlighting/lexer/parser issue
> ** Need CQL to be submitted to pygments
> * Addition of more useful documentation - tutorials, how-to guides, separate reference guide
> Current work: [https://github.com/polandll/cassandra/blob/doc_redo_asciidoc/|https://github.com/polandll/cassandra/blob/doc_redo_asciidoc/doc/Dockerfile]
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org