This repository contains the source files for the Apache Geode website.
The repository contains two branches:
The master branch contains the site's framework, comprised of the top-level landing page and the next level of pages, such as Docs, Community, and Releases, and the tools needed to compile the deployable site.
Most content resides under the website/content
directory. These sources are compiled into a deployable site by gradle scripts using a tool called Pandoc.
The asf-site branch contains a copy of the deployable site built from the master branch, fleshed-out with externally-generated content such as the User Guide and the Javadocs, which you build separately then add manually before publishing the completed site.
To deploy the Apache Geode website, you push the asf-site branch to the upstream Apache repository. An Apache “sync” tool monitors the asf-site branch of the repository and publishes your update to the Geode website after a 5-10 minute delay.
Updating the website is a two-part process:
On the master branch, update the website's framework pages.
Check out the asf-site branch and add externally-generated content, such as the User Guide and the Javadocs.
When the site's updated framework has been fleshed-out with external content, the site is ready to be deployed.
To generate the site locally, you need to install java and docker.
On the master branch, update the website's framework pages. For a general release, this would likely include:
You should still be on the master branch.
Generate the site content by navigating to the top level directory of the geode-site
repo and using gradle to compile the sources into a deployable site framework:
$ ./gradlew compile
View the generated site by running:
$ ./gradlew view
and point your browser at http://localhost:3000
to view the result.
To make further changes, stop the build (Ctrl-C), edit files, recompile, and view again.
Once you are happy with your changes, commit them to the master branch and push them to the upstream Apache repository.
$ ./gradlew publish
The gradle publish
target:
Create a local build of the User Guide as described in {geode-project-dir}/geode-book/README.md
.
Copy the User Guide to the geode-site
repo:
On the asf-site branch, create a destination directory for the User Guide. The naming convention is:
{geode-site}/website/content/docs/guide/XY
where XY
is the product version of your documentation (e.g., {geode-site}/website/content/docs/guide/17
if you are publishing the documentation for Apache Geode 1.7). So, if your current working directory is the top level of {geode-site}
, you would create the destination directory with the following command:
``` $ mkdir -p {geode-site}/website/content/docs/guide/XY ```
Navigate to the User Guide you have built in the Geode repository: {geode-project-dir}/geode-book/final_app/public/docs/guide/XY
.
Use tar
to copy the directory in order to preserve links and other filesystem niceties.
Create the tarfile in your Desktop for easy access on the retrieval side.
``` $ tar cvf ~/Desktop/new-guide-content.tar . ```
Navigate to the target directory and un-tar the userguide archive:
``` $ cd {geode-site}/website/content/docs/guide/XY $ tar xvf ~/Desktop/new-guide-content.tar ```
You should still be on the asf-site branch. Copy new javadocs directly to the directory {geode-site}/releases/latest/javadoc/
.
The new javadocs replace those currently within the directory.
Commit and push the asf-site branch. Apache detects the update and publishes it. The site should update in 5-10 minutes.
If the site does not update in 5-10 minutes, push a new commit by adding or subtracting a blank line in the top-level index.html
file. This usually does the trick.
Check your commit of the asf-site branch. The site's deployable files are at the top level, rooted at {geode-site}/index.html. Make sure that directories such as {geode-site}/docs
and {geode-site}/releases
contain the latest versions of index.html
and the docs.
For further assistance, you can
ask for advice on the Infrastructure project's HipChat room #asfinfra.