August 2022 blog "Watch the Cassandra World Party"
[cassandra-website.git] / README.md
index fda4bb4d44ea28b958fac72ad104c8dc754f258b..ef413bbec2cc472b183af88d963900ac69f7cb38 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,5 +1,41 @@
 # Apache Cassandra website
 
+Tooling to build the Apache Cassandra website and documentation.
+
+# tl;dr
+
+```
+$ git clone https://github.com/apache/cassandra-website.git
+$ cd ./cassandra-website
+
+# make sure you have docker installed
+
+# website content edits are done in ./site-content/source/modules
+# to build the website only using your local edits
+$ ./run.sh website build
+
+# open a browser window and navigate to site-content/build/html/_/index.html
+
+# Cassandra document edits are in the Apache Cassandra project
+$ git clone https://github.com/apache/cassandra.git
+$ cd ./cassandra/
+
+# in-tree Cassandra document edits are done in ./doc/modules
+# to build the website and Cassandra documentation using your local edits
+$ cd ../cassandra-website
+$ ./run.sh website build -g -u cassandra:$(pwd)/../cassandra -b cassandra:<branch-with-your-changes>
+
+# open a browser window and navigate to site-content/build/html/Cassandra/.../index.html
+```
+
+e.g.
+
+```
+$ ./run.sh website build -g -u cassandra:/Users/example/cassandra -b cassandra:example_branch
+```
+
+# Repository Layout
+
 The website repository code is separated into two main parts. These parts are represented by the directories at the root level of the project. Specifically the structure of the repository is:
 
 ```
@@ -20,7 +56,7 @@ The 'site-content' directory contains all the raw page information e.g. where to
 
 For further details about why the directories are separated as described above and why we use `antora` please see the [Details](#details) section at the bottom of this page.
 
-## Development Cycle
+# Development Cycle
 
 Making changes to the website content can be done using the following steps.
 
@@ -69,7 +105,7 @@ To build the website only, run the following command from within the `./cassandr
 $ ./run.sh website build
 ```
 
-This will build the website content using your local copy of the cassandra-website, and the current checked-out branch. Use this command if you want to make a change to a top-level webpage without building the docs for any versions of cassandra.
+This will use the current checked-out branch of your cassandra-website local copy to build the website content. In addition, the local copy of the UI bundle will be used to style the website content. Use this command if you want to make a change to a top-level webpage without building the docs for any versions of cassandra.
 
 Once building has completed, the HTML content will be in the `./site-content/build/html/` directory ready to be reviewed and committed.
 
@@ -83,11 +119,19 @@ $ ./run.sh website container -a BUILD_USER_ARG:$(whoami) -a UID_ARG:$(id -u) -a
 
 If you need to customise the container user as noted above, you must do this before you build the website or run any other website command.
 
-## Build the Website when Developing
+## Building the Website with Versioned Documentation
+
+To build the website with versioned documentation run the following command from within the `./cassandra-website` directory.
+
+```bash
+$ ./run.sh website build -g
+```
+
+# Build the Website when Developing
 
 The website tooling is very flexible and allows for a wide range of development scenarios.
 
-### Build the website from a different branch
+## Build the website from a different branch
 
 You can tell the website builder to use a different branch to the one you are on. This can be done using the following command.
 
@@ -97,7 +141,7 @@ $ ./run.sh website build -b cassandra-website:my_branch
 
 This will build the website content using your local copy of the cassandra-website, and the branch named `my_branch`.
 
-### Build the website using a local clone of the repository
+## Build the website using a local clone of the repository
 
 You can tell the website builder to use a different clone or fork of the repository.
 
@@ -109,7 +153,7 @@ $ ./run.sh website build -u cassandra-website:/local/path/to/another/clone/of/ca
 
 This will build the website using the contents of the local repository located in */local/path/to/another/clone/of/cassandra-website*
 
-### Build the website using a remote clone of the repository
+## Build the website using a remote clone of the repository
 
 To build using a remote copy of the cassandra-website run the following command.
 
@@ -145,7 +189,7 @@ All options that are available in the `build` command can be used by the `previe
 
 The cassandra-website tooling can also be used to perform a number of other operations:
 
-* Generate the Apache Cassandra documentation.
+* Generate the Apache Cassandra documentation alone.
 * Update the website styling and behaviour.
 
 ## Generating the Cassandra Documentation
@@ -184,24 +228,24 @@ In the above command, multiple branches separated by a comma (`,`) can be specif
 
 The website tooling can be used to run a complete end-to-end generation of the HTML website and versioned documentation. That is, it can first generate the AsciiDoc files for each Cassandra version, and then launch `antora` to generate the HTML website and versioned documentation for publication.
 
-### Generate the website and documentation using pre-generated Cassandra AsciiDoc in local repositories
+### Generate the website and documentation from a local repositories
 
-If you have already generated the Cassandra AsciiDoc (`.adoc`) files and committed them to your repository, you can skip the Cassandra AsciiDoc generation process.
+You can use a local copy of the Cassandra repository as the source for the documentation.
 
-To build the website using a local clone of the Cassandra repository that contains the generated AsciiDoc files, and the Cassandra Website run the following command.
+To build the website using a local clone of the Cassandra repository run the following command.
 
 ```bash
 $ ./run.sh \
   website \
   build \
-    -i \
+    -g \
     -u cassandra:/local/path/to/cassandra/repository \
     -u cassandra-website:/local/path/to/cassandra-website/repository
 ```
 
-In the above command, the `-i` option is used to tell the tooling to include the Cassandra repository when `antora` is generating the HTML. This ensures the versioned documentation HTML is generated along with the website HTML. In this case, exiting AsciiDoc files in the Cassandra repository are used to generate the versioned documentation HTML. That is, no additional operations are run to pre-generate the Cassandra AsciiDoc files.
+In the above command, the `-g` option is used to tell the tooling to generate the non-committed AsciiDoc files and include the Cassandra repository as a source when `antora` is generating the HTML. This ensures the complete versioned documentation HTML is generated along with the website HTML.
 
-### Generate the website and documentation using pre-generated Cassandra AsciiDoc in remote repositories
+### Generate the website and documentation from a remote repositories
 
 To build using a remote copy of the Cassandra repository that contains the generated AsciiDoc files, and the Cassandra Website run the following command.
 
@@ -209,7 +253,7 @@ To build using a remote copy of the Cassandra repository that contains the gener
 $ ./run.sh \
   website \
   build \
-    -i \
+    -g \
     -u cassandra:https://github.com/my_orgranisation/cassandra.git \
     -u cassandra-website:https://github.com/my_orgranisation/cassandra-website.git
 ```
@@ -220,14 +264,16 @@ You can have a combination of local and remote repository paths. For example, yo
 $ ./run.sh \
   website \
   build \
-    -i \
+    -g \
     -u cassandra:https://github.com/my_orgranisation/cassandra.git \
     -u cassandra-website:/local/path/to/cassandra-website/repository
 ```
 
-### Generate the website using local copy of the ui-bundle
+### Generate the website using your own copy of the ui-bundle
+
+By default, the local copy of the *ui-bundle.zip* located in site-ui/build/ is used by Antora to style the website when it is built. The `./run.sh` script will pass the location of ui-bundle.zip to the Docker container that executes Antora.
 
-You can use your own *ui-bundle.zip* file containing the information on how to style the website when building it. The *ui-bundle.zip* file can be generated using the `./run.sh` script. See the [Building the Site UI](#building-the-site-ui) section for furher details on how to build the *ui-bundle.zip*.
+You can use your own *ui-bundle.zip* file containing the information on how to style the website when building it. The *ui-bundle.zip* file can be generated using the `./run.sh` script. See the [Building the Site UI](#building-the-site-ui) section for further details on how to build the *ui-bundle.zip*.
 
 To supply your own *ui-bundle.zip* file when building the website, run the following command.
 
@@ -243,8 +289,6 @@ $ ./run.sh website build -z https://github.com/apache/cassandra-website/archive/
 
 The styling contained in the *ui-bundle.zip* will be applied to docs if they are being rendered as well.
 
-By default, the Docker container used to render the site will reference a GitHub release version of the *ui-bundle.zip*.
-
 ## Building the Site UI
 
 To get a list of the tasks that can be executed, run the following commands.