Skip to content
Permalink
Browse files
Update README instructions
  • Loading branch information
davebarnes97 committed Oct 3, 2018
1 parent 78714fd commit 1f0b8801e7ef55b6e4e6d79877017fa5d3890ee9
Showing 1 changed file with 99 additions and 32 deletions.
131 README.md
@@ -19,67 +19,134 @@ limitations under the License.

[![Build Status](https://travis-ci.org/apache/geode-site.svg?branch=master)](https://travis-ci.org/apache/geode-site) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)


# Apache Geode Site

This directory contains the source files for the project [website](https://geode.apache.org). Website content is written in [Markdown](https://help.github.com/articles/markdown-basics) and the site files are generated from that source by a tool called [Pandoc](http://johnmacfarlane.net/pandoc).
This repository contains the source files for the [Apache Geode website](https://geode.apache.org).

The repository contains two branches:

Source files for the website are in `website/content`. Generated files for the website are in `build/content`.
- 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.

**NOTE:** To make changes to the [Apache Geode User Guide](http://geode.apache.org/docs/), which is published to the website:
Most content resides under the `website/content` directory. These sources are compiled into a deployable site by gradle scripts using a tool called [Pandoc](http://johnmacfarlane.net/pandoc).

- Review [CONTRIBUTING](https://github.com/apache/geode/blob/develop/geode-docs/CONTRIBUTE.md) in the Geode repository for information about contributing to the documentation source files.
- Follow the [README](https://github.com/apache/geode/blob/develop/geode-book/README.md) in the Geode repository's `geode-book` directory for information about building a local version of the guide and adding it to the website.
- 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.

The website is updated by a "sync" tool that monitors the __asf-site__ branch
of our Git repo, so after making changes you must place your updated source
and generated files on the __asf-site__ branch and push.
The content will be published to the
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](http://geode.apache.org) after a 5-10 minute delay.


# Update procedure
Updating the website is a two-part process:

1. On the __master__ branch, update the website's framework pages.

1. 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.

## Prerequisites

To generate the site locally, you need to install java and docker.

## How to change/update the website
## Update the website framework

### 1. Find and edit the source files you need to change
On the __master__ branch, update the website's framework pages. For a general release, this would likely include:

Source files for the website are in ``website/content``. When changing the content of the site, find the Markdown files that you
need to edit and make your change. If you need to change the layout or styling of the site, then you will probably need to change
- {geode-site}/website/content/index.html
- {geode-site}/website/content/community/index.html
- {geode-site}/website/content/docs/index.html
- {geode-site}/website/content/releases/index.html
- If you need to change the layout or styling of the site, then you will probably need to change
an HTML, JS or CSS file.

### 2. Locally generate the site and test your changes

To generate the site content, navigate to the top level directory of the repo and use gradle to run the `nanoc` compiler:
## Locally generate the site framework and review your changes

$ ./gradlew compile
You should still be on the __master__ branch.

To view the generated site, run:
1. 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
```
2. View the generated site by running:

```
$ ./gradlew view
```

and point your browser at `http://localhost:3000` to view the result.

and point your browser at `http://localhost:3000`. To make further changes, stop the build, edit files, recompile, and view again.
3. To make further changes, stop the build (Ctrl-C), edit files, recompile, and view again.

### 3. Publish your changes to the site
4. Once you are happy with your changes, commit them to the __master__ branch and push them to the upstream Apache repository.

Once you are happy with your changes, commit them to the __master__ branch.
The changes also need to be propagated to the __asf-site__ branch. Run the
gradle command
## Add externally-generated content to the site framework

### 1. On the __master__ branch, run the gradle command:

$ ./gradlew publish

to checkout the __asf-site__ branch and copy the website files. You will
need to manually commit and push your changes on the __asf-site__ branch.
The gradle `publish` target:

- Checks out the __asf-site__ branch, and
- Copies the website files to their deployment directories.


### 2. Add a new user guide

1. Create a local build of the User Guide as described in `{geode-project-dir}/geode-book/README.md`.

1. Copy the User Guide to the `geode-site` repo:

The site should update in 5-10 minutes. If it does not,
1. On the __asf-site__ branch, create a destination directory for the User Guide. The naming convention is:

- Push a new commit by adding or subtracting a blank line, or
```
{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
```

1. Navigate to the User Guide you have built in the Geode repository: `{geode-project-dir}/geode-book/final_app/public/docs/guide/XY`.

1. 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
```

### 3. Publish new javadocs

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.

## Deploy the update
Commit and push the __asf-site__ branch. Apache detects the update and publishes it. The site should update in 5-10 minutes.

## Troubleshooting
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.

For further assistance, you can
- [file a JIRA against the INFRA project](https://issues.apache.org/jira/browse/INFRA), or
- ask for advice on the Infrastructure project's HipChat room
[#asfinfra](https://www.hipchat.com/g4P84gemn).
- ask for advice on the Infrastructure project's HipChat room [#asfinfra](https://www.hipchat.com/g4P84gemn).




### 4. Publishing new javadocs

Commit and push new javadocs directly on the __asf-site__ branch.
New javadocs _replace_ those currently within the directory
`geode-site/releases/latest/javadoc/`.

0 comments on commit 1f0b880

Please sign in to comment.