Rails Documentation Server Support

Dependencies

• RVM

• rvm install 3.2.5

• rvm install 3.1.4

• rvm install 2.7.6

• rvm install 2.5.3

• rvm use 2.5.3 do gem install bundler -v 1.16.1 --no-rdoc --no-ri

• rvm use 2.5.3 do gem install bundler -v 2.1.4 --no-rdoc --no-ri

• rvm use 2.5.3 do gem install bundler -v 2.2.3 --no-rdoc --no-ri

• rvm use 2.7.6 do gem install bundler -v 2.2.3 --no-doc

• rvm use 3.1.4 do gem install bundler --no-doc

• rvm use 3.2.5 do gem install bundler --no-doc

• kindlegen must be in PATH (download))

• Install imagemagick, for convert, used by the guides generator

  • Linux: sudo apt-get install imagemagick
  • macOS: brew install imagemagick

• Nokogiri's dependencies (present in some Gemfiles):

  • Linux: sudo apt-get install libxslt-dev libxml2-dev
  • macOS: brew install libxml2 (see nokogiri installation instructions)

The Ruby and bundler dependencies are not hard, we fix concrete versions because these are known to work. Ruby and bundler versions are configurable per release, so this is forward-compatible, just add new versions if needed and configure their target generator to use them.

Locale

Make sure the locale is UTF8, in Linux/macOS run locale and see if the values are "en_US.UTF-8" in general.

In Ubuntu edit the file /etc/default/locale and put

LC_ALL=en_US.UTF-8
LANG=en_US.UTF-8

Setup

After cloning the repository, add the environment configuration to your profile:

echo "" >> ~/.profile
echo "# Source rails-docs-server environment configuration" >> ~/.profile
echo "[ -f ~/rails-docs-server/config/profile ] && . ~/rails-docs-server/config/profile" >> ~/.profile

Or simply run the cron job once, which will automatically add this line if it doesn't exist.

Note: The rails_master_hook.sh script automatically ensures ~/.profile sources config/profile, so any updates to config/profile will be picked up automatically without overwriting your existing ~/.profile customizations.

Deployment

Just push to main. The cron job in the docs server pulls before invoking the docs generator.

Test Suite

In order to run the test suite you need a recent version of minitest:

• gem install minitest -N

There are two tasks: The default task, test, tests everything except actual docs generation. The test:all task runs the entire suite including doc generation for a few releases, this one takes about 20 minutes in my laptop.