This document contains instructions for building and viewing the Apache Geode Native Client User Guide.
The Geode-Native repository provides the full source for the Apache Geode Native Client User Guide in markdown format (see geode-project-dir/geode-docs/CONTRIBUTE.md for more information on how to use markdown in this context). Users can build the markdown into an HTML user guide using Bookbinder and the instructions below.
Bookbinder is a Ruby gem that binds a unified documentation web application from markdown, html, and/or DITA source material. The source material for bookbinder must be stored either in local directories or in GitHub repositories. Bookbinder runs Middleman to produce a Rackup app that can be deployed locally or as a web application.
Bookbinder is meant to be used from within a project called a book. The book includes a configuration file that describes which documentation repositories to use as source materials. Bookbinder provides a set of scripts to aggregate those repositories and publish them to various locations.
For Geode Native Client, a preconfigured book is provided in the directory geode-native-project-dir/docs/geode-native-book, which gathers content from the directory geode-native-project-dir/docs/geode-native-docs. You can use this configuration to build an HTML version of the Apache Geode Native Client User Guide on your local system.
For ease of use, a Docker image is provided that contains a self-consistent Bookbinder environment. Install Docker if you have not already done so.
Navigate to the directory that contains the Dockerfile and run the docker build
command to create the Bookbinder-enabled Docker image:
$ cd geode-native/docs/docker $ docker build -t geode-native-userman .
Run the Docker image in interactive mode with a command similar to the following:
$ docker run -it -p 9292:9292 -p 1234:1234 -v PATH-TO-GEODE-NATIVE/docs:/docs geode-native-userman
where PATH-TO-GEODE-NATIVE
is the fully-qualified path to the geode-native repo. This brings up the interactive Docker container, with /
as your current working directory.
To build the documentation, cd
to the book directory:
$ cd docs/geode-native-book
Run bundle install
to install the dependencies required to build the user guide.
$ bundle install
Invoke bookbinder to build the user guide. Bookbinder converts the markdown source into HTML, which it puts in the final_app
directory:
$ bundle exec bookbinder bind local
To start a local website of the Apache Geode Native Client User Guide, navigate to the final_app
directory and run rackup
:
$ cd final_app
$ rackup
Note: You may be prompted to run bundle install
to supply any missing components. Do that, then re-try the rackup
command.
You can now view the local documentation in a browser at http://localhost:9292.