GEODE-1952 Move docs build README; edit build instructions
Project: http://git-wip-us.apache.org/repos/asf/incubator-geode/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-geode/commit/742d3068 Tree: http://git-wip-us.apache.org/repos/asf/incubator-geode/tree/742d3068 Diff: http://git-wip-us.apache.org/repos/asf/incubator-geode/diff/742d3068 Branch: refs/heads/feature/GEODE-1952-2 Commit: 742d306806f9ba19feb7a9d1ea5cd0997aa8069d Parents: 8d1b0d4 Author: Joey McAllister <jmcallis...@pivotal.io> Authored: Fri Oct 14 12:13:15 2016 -0700 Committer: Joey McAllister <jmcallis...@pivotal.io> Committed: Fri Oct 14 12:13:15 2016 -0700 ---------------------------------------------------------------------- geode-book/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++- geode-docs/CONTRIBUTE.md | 8 +++--- geode-docs/README.md | 53 ------------------------------------- 3 files changed, 63 insertions(+), 59 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/742d3068/geode-book/README.md ---------------------------------------------------------------------- diff --git a/geode-book/README.md b/geode-book/README.md index a1c1602..198becc 100644 --- a/geode-book/README.md +++ b/geode-book/README.md @@ -1 +1,60 @@ -For information about writing, editing, building, and publishing the Apache Geode documentation, please view the `README.md` and `CONTRIBUTING.md` files in the `geode-docs` directory. \ No newline at end of file +# Apache Geode End-User Documentation + +Apache Geode provides the full source for end-user documentation in markdown format (see `../geode-docs/CONTRIBUTE.md`). 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. + +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](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. + +- [Prerequisites](#prerequisites) +- [Bookbinder Usage](#bookbinder-usage) +- [Building the Documentation](#building-the-documentation) + +## Prerequisites + +Bookbinder requires Ruby version 2.0.0-p195 or higher. + +Follow the instructions below to install Bookbinder: + +1. Add gem "bookbindery" to your Gemfile. +2. Run `bundle install` to install the dependencies specified in your Gemfile. + +## Bookbinder Usage + +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, 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. + +The installed `config.yml` file configures the Geode book for building locally. The file configures the local directory for the markdown source files. + +## Building the Documentation + +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: + +``` + $ bundle install +``` + + Note: You will not have to run `bundle install` on subsequent builds. + +2. 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. + +3. Navigate to the `geode-book/final_app/` and enter: + + ``` + $ bundle install + ``` + Note: You will not have to run `bundle install` on subsequent builds. + +4. To start the website locally, enter: + + ``` + $ rackup + ``` + + You can now view the local documentation at <http://localhost:9292>. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/742d3068/geode-docs/CONTRIBUTE.md ---------------------------------------------------------------------- diff --git a/geode-docs/CONTRIBUTE.md b/geode-docs/CONTRIBUTE.md index 979474e..8ff2502 100644 --- a/geode-docs/CONTRIBUTE.md +++ b/geode-docs/CONTRIBUTE.md @@ -6,6 +6,8 @@ Apache Geode welcomes your contributions to the community's documentation effort - [Working with Images and Graphics](#working-with-images-and-graphics) - [Writing Guidelines](#writing-guidelines) +For instructions on building the documentation locally, see `../geode-book/README.md`. + ## Working with Markdown Files You can edit markdown files in any text editor. For more, read [Daring Fireball's Markdown Syntax page](https://daringfireball.net/projects/markdown/syntax). @@ -23,13 +25,9 @@ The Wikipedia page [Comparison of Vector Graphics Editors](http://en.wikipedia.o The most important advice we can provide for working with the Apache Geode docs is to spend some time becoming familiar with the existing source files and the structure of the project directory. In particular, note the following conventions and tips: - Top-level subdirectories organize topics into "books": basic_config, configuring, developing, etc. - - Use lowercase characters for all file and directory names. Separate words in filenames with an underscore (`_`) character. - - Use the `.md` file extension for topic files. - - Add new topics to the existing directories by subject type. Only create a new directory if you are starting a new subject or a new book. - - To start a new topic, you can make a copy of an existing file with similar content and edit it. - - Use the appropriate document type for the content you are writing. Create multiple topics if you are writing overview, procedural, and reference content. +- To edit elements in the navigation pane (the "subnav") that appears on the left side of the documentation, navigate to `../geode-book/master_middleman/source/subnavs/geode-subnav.md`. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/742d3068/geode-docs/README.md ---------------------------------------------------------------------- diff --git a/geode-docs/README.md b/geode-docs/README.md deleted file mode 100644 index 9fb5870..0000000 --- a/geode-docs/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# Apache Geode End-User Documentation - -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. - -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](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. - -- [Prerequisites](#prerequisites) -- [Bookbinder Usage](#bookbinder-usage) -- [Building the Documentation](#building-the-documentation) - -## Prerequisites - -Bookbinder requires Ruby version 2.0.0-p195 or higher. - -Follow the instructions below to install Bookbinder: - -1. Add gem "bookbindery" to your Gemfile. -2. Run `bundle install` to install the dependencies specified in your Gemfile. - -## Bookbinder Usage - -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, 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. - -The installed `config.yml` file configures the Geode book for building locally. The file configures the local directory for the markdown source files. - -## Building the Documentation - -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: - - ``` - $ bundle install - ``` - -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, which it puts in the `final_app` directory. - -3. To view the local documentation, do the following: - - ``` - $ cd final_app - $ rackup - ``` - - You can now view the local documentation at <http://localhost:9292>.
