ceph/src/rocksdb/docs/README.md

   1 ## User Documentation for rocksdb.org
   2
   3 This directory will contain the user and feature documentation for RocksDB. The documentation will be hosted on GitHub pages.
   4
   5 ### Contributing
   6
   7 See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to add or modify content.
   8
   9 ### Run the Site Locally
  10
  11 The requirements for running a GitHub pages site locally is described in [GitHub help](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#requirements). The steps below summarize these steps.
  12
  13 > If you have run the site before, you can start with step 1 and then move on to step 5.
  14
  15 1. Ensure that you are in the `/docs` directory in your local RocksDB clone (i.e., the same directory where this `README.md` exists). The below RubyGems commands, etc. must be run from there.
  16
  17 1. Make sure you have Ruby and [RubyGems](https://rubygems.org/) installed.
  18
  19    > Ruby >= 2.2 is required for the gems. On the latest versions of Mac OS X, Ruby 2.0 is the
  20    > default. Use `brew install ruby` (or your preferred upgrade mechanism) to install a newer
  21    > version of Ruby for your Mac OS X system.
  22
  23 1. Make sure you have [Bundler](http://bundler.io/) installed.
  24
  25     ```
  26     # may require sudo
  27     gem install bundler
  28     ```
  29 1. Install the project's dependencies
  30
  31     ```
  32     # run this in the 'docs' directory
  33     bundle install
  34     ```
  35
  36     > If you get an error when installing `nokogiri`, you may be running into the problem described
  37     > in [this nokogiri issue](https://github.com/sparklemotion/nokogiri/issues/1483). You can
  38     > either `brew uninstall xz` (and then `brew install xz` after the bundle is installed) or
  39     > `xcode-select --install` (although this may not work if you have already installed command
  40     > line tools).
  41
  42 1. Run Jekyll's server.
  43
  44     - On first runs or for structural changes to the documentation (e.g., new sidebar menu item), do a full build.
  45
  46     ```
  47     bundle exec jekyll serve
  48     ```
  49
  50     - For content changes only, you can use `--incremental` for faster builds.
  51
  52     ```
  53     bundle exec jekyll serve --incremental
  54     ```
  55
  56     > We use `bundle exec` instead of running straight `jekyll` because `bundle exec` will always use the version of Jekyll from our `Gemfile`. Just running `jekyll` will use the system version and may not necessarily be compatible.
  57
  58     - To run using an actual IP address, you can use `--host=0.0.0.0`
  59
  60     ```
  61     bundle exec jekyll serve --host=0.0.0.0
  62     ```
  63
  64     This will allow you to use the IP address associated with your machine in the URL. That way you could share it with other people.
  65
  66     e.g., on a Mac, you can your IP address with something like `ifconfig | grep "inet " | grep -v 127.0.0.1`.
  67
  68 1. Either of commands in the previous step will serve up the site on your local device at http://127.0.0.1:4000/ or http://localhost:4000.
  69
  70 ### Updating the Bundle
  71
  72 The site depends on Github Pages and the installed bundle is based on the `github-pages` gem.
  73 Occasionally that gem might get updated with new or changed functionality. If that is the case,
  74 you can run:
  75
  76 ```
  77 bundle update
  78 ```
  79
  80 to get the latest packages for the installation.