This document contains instructions for building and viewing the Apache Geode Native Client User Guides.
The Geode-Native repository provides the full source for the Apache Geode Native Client User Guides 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 (available at rubygems.org ) 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.
The User Guide can be produced in two versions: one for the .NET native client, the other for the C++ native client.
Documentation can be built and previewed using the utility script at {geode-project-dir}/docs/docker. This script uses a Docker image that provides the tools to build and view the guide, including Ruby, Bookbinder, and Rackup.
For the C++ guide:
$ cd {geode-native-project-dir}/docs/docker
$ ./preview-user-guide.sh cpp
For the .NET guide:
$ cd {geode-native-project-dir}/docs/docker
$ ./preview-user-guide.sh dotnet
Once the script shows it is listening on a local address, you can use a browser to view the user guide on that address.
For example:
$ ./preview-user-guide.sh cpp
...
...
Puma starting in single mode...
* Version 4.3.8 (ruby 2.5.9-p229), codename: Mysterious Traveller
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://0.0.0.0:9292
Use Ctrl-C to stop
You will find the user guide at 0.0.0.0:9292
.
Files generated by Bookbinder will be at {geode-project-dir}/docs/geode-native-book-cpp/final_app
for the C++ guide, and at {geode-project-dir}/docs/geode-native-book-dotnet/final_app
for the .NET guide.
Bookbinder requires Ruby version 2.3.3 or higher.
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 for each user guide (C++ and .NET) in the directories {geode-native-project-dir}/docs/geode-native-book-cpp
and {geode-native-project-dir}/docs/geode-native-book-dotnet
. Each book gathers content from the language-specific directory geode-native-project-dir/docs/geode-native-docs-cpp or geode-native-docs-dotnet. You can use this configuration to build an HTML version of the Apache Geode Native Client User Guides on your local system.
-
The GemFile in each book directory already defines the gem "bookbindery" dependency. Make sure you are in the
_geode-native-project-dir_/docs/geode-native-book-cpp
or_geode-native-project-dir_/docs/geode-native-book-dotnet
(depending if you want to build the C++ or .NET user guide respectively) directory and enter:For the C++ guide:
$ cd docs/geode-native-book-cpp $ bundle install
For the .NET guide:
$ cd docs/geode-native-book-dotnet $ bundle install
Note: You will not have to run bundle install on subsequent builds.
-
To build the documentation locally using the installed config.yml file, enter:
$ bundle exec bookbinder bind local
Bookbinder converts the markdown source into HTML, which it puts in the
final_app
directory. -
To start a local website of the Apache Geode Native Client User Guide, you have to execute Rackup from the
final_app
directory:For C++ guide:
$ cd docs/geode-native-book-cpp/final_app $ bundle exec rackup
For .NET guide:
$ cd docs/geode-native-book-dotnet/final_app $ bundle exec rackup
You can now view the local documentation at
http://localhost:9292
.