[
https://issues.apache.org/jira/browse/CASSANDRA-16029?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Lorina Poland updated CASSANDRA-16029:
--------------------------------------
Description:
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]
Relevant Links:
Original source for antora-ui: [https://gitlab.com/antora/antora-ui-default]
(Mozilla public license 2.0)
Current working repo for antora-ui:
[https://github.com/ianjevans/antora-ui-datastax] in oss branch
Lunr search implemented with: [https://github.com/Mogztter/antora-lunr] and
[https://github.com/Mogztter/antora-site-generator-lunr]
(MIT license)
Codeblock tabs implemented with: Dan Allen's tabs-block.js code (finding
source).
was:
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]
> 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]
> Relevant Links:
> Original source for antora-ui: [https://gitlab.com/antora/antora-ui-default]
> (Mozilla public license 2.0)
> Current working repo for antora-ui:
> [https://github.com/ianjevans/antora-ui-datastax] in oss branch
> Lunr search implemented with: [https://github.com/Mogztter/antora-lunr] and
> [https://github.com/Mogztter/antora-site-generator-lunr]
> (MIT license)
> Codeblock tabs implemented with: Dan Allen's tabs-block.js code (finding
> source).
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
