[GitHub] [cassandra] anthony-grasso-datastax commented on a change in pull request #1128: (trunk) CASSANDRA-16763 Create Cassandra documentation content for new website

[GitBox <gi...@apache.org>]

anthony-grasso-datastax commented on a change in pull request #1128:
URL: https://github.com/apache/cassandra/pull/1128#discussion_r774812153



##########
File path: doc/README.md
##########
@@ -36,20 +36,19 @@ Official documentation
 ----------------------
 
 The source for the official documentation for Apache Cassandra can be found in
-the `source` subdirectory. The documentation uses [sphinx](http://www.sphinx-doc.org/)
-and is thus written in [reStructuredText](http://docutils.sourceforge.net/rst.html).
+the `source` subdirectory. The documentation uses [antora](http://www.antora.org/)
+and is thus written in [asciidoc](http://asciidoc.org).
+
+To build the HTML documentation, you will need to first install antora and the
+[Apache Cassandra theme](https://???). To add search, [lunr](https://lunrjs.com) must be installed.
 
-To build the HTML documentation, you will need to first install sphinx and the
-[sphinx ReadTheDocs theme](https://pypi.org/project/sphinx_rtd_theme/).
-When using Python 3.6 on Windows, use `py -m pip install sphinx sphinx_rtd_theme`, on unix
-use:
 ```
-pip install sphinx sphinx_rtd_theme
+npm i -g @antora/cli @antora/site-generator-default
+npm install lunr
 ```
 
 The documentation can then be built from this directory by calling `make html`
-(or `make.bat html` on windows). Alternatively, the top-level `ant gen-doc`
-target can be used.  When using Python 3.6 on Windows, use `sphinx_build -b html source build`.
+Alternatively, the top-level `ant gen-doc` target can be used.  

Review comment:
       Good catch. I guess we have a Makefile that does part of what the `generate_cassandra_versioned_docs` function in the [docker-entrypoint.sh](https://github.com/apache/cassandra-website/blob/trunk/site-content/docker-entrypoint.sh#L23-L139) does. That is, build the jar files, then call the nodetool and cassandra configuration adoc generation scripts. This would be the most that `gen-doc` could do and should be enough to weed out any breakages. The README also needs to be updated. We would need to make this change on all three branches.
   
   As a bonus, we could probably update the `generate_cassandra_versioned_docs` function to call `ant gen-doc`.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org