You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by sb...@apache.org on 2016/10/25 06:20:46 UTC
[40/50] [abbrv] incubator-geode git commit: GEODE-1952 Update docs
README, config
GEODE-1952 Update docs README, config
Project: http://git-wip-us.apache.org/repos/asf/incubator-geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-geode/commit/36d1f39d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-geode/tree/36d1f39d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-geode/diff/36d1f39d
Branch: refs/heads/master
Commit: 36d1f39d68a847dc574e267c51efa89f9c980bd6
Parents: 7592ba1
Author: Joey McAllister <jm...@pivotal.io>
Authored: Tue Oct 11 15:54:54 2016 -0700
Committer: Joey McAllister <jm...@pivotal.io>
Committed: Tue Oct 11 15:54:54 2016 -0700
----------------------------------------------------------------------
geode-book/config.yml | 9 ++---
geode-docs/README.md | 92 +++++++++++++++++++++-------------------------
2 files changed, 44 insertions(+), 57 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/36d1f39d/geode-book/config.yml
----------------------------------------------------------------------
diff --git a/geode-book/config.yml b/geode-book/config.yml
index 1a74e82..74003f0 100644
--- a/geode-book/config.yml
+++ b/geode-book/config.yml
@@ -1,6 +1,5 @@
book_repo: apache/incubator-geode/geode-book
-
-public_host: http://geode.incubator.apache.org/docs/
+public_host: localhost
sections:
- repository:
@@ -11,13 +10,11 @@ sections:
template_variables:
support_url: http://geode.incubator.apache.org/community
product_url: http://geode.incubator.apache.org/
- book_title: Apache Geode (Incubating) Documentation (Develop)
- cse_id: 012029519579280034868:3hzywhss5ik
+ book_title: Apache Geode (Incubating) Documentation
support_link: <a href="http://geode.incubator.apache.org/community" target="_blank">Community</a>
support_call_to_action: <a href="http://geode.incubator.apache.org/community" target="_blank">Need Help?</a>
product_link: <div class="header-item"><a href="http://geode.incubator.apache.org/">Back to Geode Page</a></div>
- ga_account_id: UA-39702075-1
domain_name: apache.org
- book_title_short: Geode Docs (Develop)
+ book_title_short: Geode Docs
broken_link_exclusions: iefix|using_custom_classes|arrowhead|cppdocs|DotNetDocs
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/36d1f39d/geode-docs/README.md
----------------------------------------------------------------------
diff --git a/geode-docs/README.md b/geode-docs/README.md
index a018ca1..bc70325 100644
--- a/geode-docs/README.md
+++ b/geode-docs/README.md
@@ -1,93 +1,83 @@
# Project Geode End-User Documentation
-The latest check-ins to `project-geode/docs` are automatically built and published to <http://geode-docs.cfapps.io>.
+Apache Geode provides the full source for end-user documentation in markdown format. The latest check-ins to `incubator-geode/geode-docs` are regularly built and published to http://geode.incubator.apache.org/docs/. Users can build the markdown into an HTML user guide using [Bookbinder](https://github.com/pivotal-cf/bookbinder) and the instructions below.
-Project Geode provides the full source for end-user documentation in markdown format. The markdown can be built into HTML using [Bookbinder](https://github.com/pivotal-cf/bookbinder).
+Bookbinder is a 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](http://middlemanapp.com/) to produce a Rackup app that can be deployed locally or as a Web application.
-Bookbinder is a gem that binds together 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](http://middlemanapp.com/) to produce a Rackup app that can be deployed locally or as a Web application.
+This document contains instructions for building and viewing the Geode documentation locally, as well as for publishing it to the Geode website. It contains the sections:
-This document contains instructions for building the local Geode documentation and publishing it to Cloud Foundry or Pivotal Web Services. It contains the sections:
-
-- [Bookbinder Usage](#usage)
- [Prerequisites](#prereq)
+- [Bookbinder Usage](#usage)
- [Building the Documentation](#building)
- [Publishing the Documentation](#publishing)
-- [Getting More Information](#moreinfo)
-[]()
+## Prerequisites
-## Bookbinder Usage
+Bookbinder requires Ruby version 2.0.0-p195 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.
+Follow the instructions below to install Bookbinder:
-For Geode, a preconfigured **book** is provided in the directory `/geode-book`. You can use this configuration to build HTML for project Geode on your local system.
+1. Add gem "bookbindery" to your Gemfile.
+2. Run `bundle install` to install the dependencies specified in your Gemfile.
-[]()
-
-## Prerequisites
+## Bookbinder Usage
-- Bookbinder requires Ruby version 2.0.0-p195 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.
-## Building the Documentation
+For Geode, a preconfigured **book** is provided in the directory `geode-book`, which gathers content from the directory `geode-docs`. You can use this configuration to build HTML for Geode on your local system.
-1. Begin by moving or copying the `/geode-book directory` to a directory that is parallel to `project-geode/docs`. For example:
+The installed `config.yml` file configures the Geode book for building locally. The file configures the local directory for the markdown source files. It uses the following configuration:
```
- $ cd /repos/project-geode/docs
- $ cp -r geode-book ..
- $ cd ../geode-book
+book_repo: apache/incubator-geode/geode-book
+public_host: localhost
+
+sections:
+- repository:
+ name: geode-docs
+ directory: docs
+ subnav_template: geode-subnav
+
+template_variables:
+ support_url: http://geode.incubator.apache.org/community
+ product_url: http://geode.incubator.apache.org/
+ book_title: Apache Geode (Incubating) Documentation
+ support_link: <a href="http://geode.incubator.apache.org/community" target="_blank">Community</a>
+ support_call_to_action: <a href="http://geode.incubator.apache.org/community" target="_blank">Need Help?</a>
+ product_link: <div class="header-item"><a href="http://geode.incubator.apache.org/">Back to Geode Page</a></div>
+ domain_name: apache.org
+ book_title_short: Geode Docs
+
+broken_link_exclusions: iefix|using_custom_classes|arrowhead|cppdocs|DotNetDocs
```
-2. The GemFile in the book directory already defines the `gem "bookbindery"` dependency. Make sure you are in the relocated book directory and enter:
-
- ```
- $ bundle install
- ```
+## Building the Documentation
-3. The installed `config.yml` file configures the Project Geode book for building locally. The installed file configures the local directory for the markdown source files. It uses the configuration:
+1. The GemFile in the `geode-book` directory already defines the `gem "bookbindery"` dependency. Make sure you are in the `geode-book` directory and enter:
```
- book_repo: project-geode/geode-book
- public_host: localhost
-
- sections:
- - repository:
- name: gemfire/docs-geode-md
- directory: docs-geode
- subnav_template: geode-nav
-
- template_variables:
- product_url: http://geode.incubator.apache.org
- book_title: Project Geode Documentation
+ $ bundle install
```
-4. Build the files locally using the installed `config.yml` file. Execute the command:
+2. To build the files locally using the installed `config.yml` file, enter:
```
$ bundle exec bookbinder bind local
```
- Bookbinder converts the markdown source into HTML, putting the final output in the `final_app` directory.
+ Bookbinder converts the markdown source into HTML, which it puts in the `final_app` directory.
-5. To view the local documentation:
+5. To view the local documentation, do the following:
```
$ cd final_app
$ rackup
```
- You can now view the local documentation at <http://localhost:9292>
-
-[]()
+ You can now view the local documentation at <http://localhost:9292>.
## Publishing the Documentation
Because the `final_app` directory contains the full output of the HTML conversion process, you can easily publish this directory as a hosted Web application.
-[]()
-
-## Getting More Information
-
-Bookbinder provides additional functionality to construct books from multiple Github repos, to perform variable substitution, and also to automatically build documentation in a continuous integration pipeline. For more information, see <https://github.com/pivotal-cf/bookbinder>.
-
-The latest check-ins to `gemfire/docs-geode-md` are automatically built and published to <http://geode-docs.cfapps.io>.
+To publish the Geode documentation you built locally to the Geode website, move the contents of the directory `geode-book/final_app/public/docs` to the directory `geode-site/website/content/docs`. Then, follow the instructions for updating the website located at `geode-site/website/README.md`.
\ No newline at end of file