Lorina Poland created CASSANDRA-16029:
-----------------------------------------
Summary: 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
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-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
