Contributing to Documentation

Table of contents

1. Contributing to Documentation
   1. Process for updating documentation
   2. Dependencies
      1. macOS
      2. Linux
   3. Build and serve the docs locally

This guide will walk you through setting up your machine for contributing to FireFly documentation. Documentation contributions are extremely valuable. If you discover something is missing in the docs, we would love to include your additions or clarifications to help the next person who has the same question.

This doc site is generated by a set of Markdown files in the main FireFly repository, under the ./docs directory. You can browse the source for the current live site in GitHub here: https://github.com/hyperledger/firefly/tree/main/docs

Process for updating documentation

The process for updating the documentation is really easy! You’ll follow the same basic steps outlined in the same steps outlined in the Contributor’s guide. Here are the detailed steps for contributing to the docs:

1. Fork https://github.com/hyperledger/firefly
2. Clone your fork locally to your computer
3. Follow the steps below to view your local copy of the docs in a browser
4. Make some improvements to the Markdown files
5. Verify that your changes look they way you want them to in your browser
6. Create a new git commit with your changes. Be sure to sign-off on your commit by using git commit -s!
7. Push your changes
8. Open a Pull Request to incorporate your changes back into the hyperledger/firefly repo

Dependencies

The FireFly docs site uses GitHub pages, which uses a tool called Jekyll to convert Markdown files into HTML files that can be read in your browser. Basically that means in order to build and view the pages locally on your machine, you need to have Jekyll. Jekyll is a Ruby app, so you’ll also need to have Ruby, and the Ruby bundler app to install Jekyll’s dependencies. The good news is these things are very easy to set up.

macOS

If you’re using an Intel Mac, you are already good to go! macOS already comes with ruby and bundle installed and set up already. You don’t need to do anything extra. However, it may be advisable to install a newer version of Ruby anyway.

NOTE: From the macOS Catalina 10.15 Release Notes: Scripting language runtimes such as Python, Ruby, and Perl are included in macOS for compatibility with legacy software. Future versions of macOS won’t include scripting language runtimes by default, and might require you to install additional packages. If your software depends on scripting languages, it’s recommended that you bundle the runtime within the app. (49764202)

If you’re using an Apple Silicon based Mac, the version of Ruby that comes with macOS supports both Intel and ARM binaries which unfortunately ends up causing some problems when installing certain gems. We recommend installing Ruby with brew and setting it on your path. This will also give you a newer version of Ruby. To do this, run:

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc

Linux

You will need to install ruby and bundle and have them on your path to build and serve the docs locally. On Ubuntu, to install these, run the following commands:

sudo apt-get update
sudo apt-get install ruby ruby-bundler

Build and serve the docs locally

To build and serve the docs locally, from the project root, navigate to the docs directory:

cd docs

Install docs dependencies:

bundle install

And start the Jekyll test server:

bundle exec jekyll serve --livereload

You should now be able to open http://127.0.0.1:4000/firefly/index.html in your browser and see a locally hosted version of the doc site.

As you make changes to files in the ./docs directory, Jekyll will automatically rebuild the pages, and notify you of any errors or warnings in your terminal. If you have a browser open, it will automatically reload when changes are made to pages.