This repository contains the source files for the Apache Geode website.
The repository contains two branches:
The master branch contains the site's HTML framework, composed 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.
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, which includes all non-framework content such as the User Guide and the Javadocs, which you build separately then add manually on the asf-site branch before publishing the completed site. Stylesheets also reside on the asf-site branch.
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.
Other support tools you may need include:
On the master branch, update the website's framework pages. For a general release, this would likely include:
A couple of notes specific to documentation:
redirects.rb
substitutions provided with the Geode and Geode Native user guides. On this site, the file website/content/.htaccess
provides redirect information. Edit this file on the master branch, and the gradlew publish
operation will propagate your changes to the asf-site branch.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
You may need to suppress rat checking: add -x rat
to the end of the .gradlew
command.
View the generated site by running:
$ ./gradlew view
and point your browser at http://localhost:3000
to view the result.
You may need to suppress rat checking: add -x rat
to the end of the .gradlew
command.
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:
HEADS-UP The gradlew publish
command does not update the css
and stylesheets
directories. If you made format changes there, you must manually merge the new versions of those files from the master branch.
gradlew publish
command, copy the new versions to the appropriate directories in the asf-site branch.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}/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.14). 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}/docs/guide/114 ```
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}/docs/guide/XY $ tar xvf ~/Desktop/new-guide-content.tar ```
Replace the entire docs/guide/latest
directory with a copy of the latest user guide‘s directory. Use tar
(rather than cp
) to preserve the original directory’s structure.
``` $ cd {geode-site}/docs/guide $ rm -rf latest $ mkdir latest $ cd latest $ (cd ../XY && tar cf - *) | (tar xf -) ```
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.
DO NOT commit the {geode-site}/build directory. This is the place where files compiled on the master branch are placed, then retrieved after the switch to the asf-site branch. It must be freshly generated with each iteration, not saved to the repo.
For further assistance, you can
ask for advice on the Infrastructure project's HipChat room #asfinfra.