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/release/1.0.0-incubating Commit: 36d1f39d68a847dc574e267c51efa89f9c980bd6 Parents: 7592ba1 Author: Joey McAllister <jmcallis...@pivotal.io> Authored: Tue Oct 11 15:54:54 2016 -0700 Committer: Joey McAllister <jmcallis...@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
