Contributing to Rockstor documentation

Steps for contributing to rockstor-doc repo are similar to contributing to rockstor-core, as we follow the same fork and pull request model. We’ll assume you have basic proficiency with Git and are familiar with using a text editor or IDE of your choice. Emacs, Vim, Eclipse and PyCharm are some recommendations. Or you may be able to use an online such as https://livesphinx.herokuapp.com/.

Environment setup

Clone the repository

We’ll assume that you have your laptop ready with Git and an editor installed. Since we rely on github services, you need to create a profile on github.com. Once you have your profile set-up on github.com, follow these steps:

Go to rockstor-doc repo and click on the Fork button. This will fork the repository into your profile which serves as your private Git remote called origin. The next few Git steps are demonstrated on a Linux terminal. They work the same on a Mac too.

you@laptop:~> mkdir ~/dev; cd ~/dev
you@laptop:~/dev> git clone git@github.com:your_github_username/rockstor-doc.git

The above command creates a local rockstor-doc Git repo in a new directory by the same name (rockstor-doc) inside the new “~/dev” directory. Change into it.

you@laptop:~/dev> cd rockstor-doc

Configure this new Git repo with your name and email address. This is required to accurately record collaboration.

you@laptop:~/dev/rockstor-doc> git config user.name "Firstname Lastname"
you@laptop:~/dev/rockstor-doc> git config user.email your_email_address

Add a remote called upstream to periodically rebase your local repository with changes in the upstream made by other contributors.

you@laptop:~/dev/rockstor-doc> git remote add upstream https://github.com/rockstor/rockstor-doc.git

If desired, you can now verify these settings are correct by displaying the Git configuration for the local repository:

you@laptop:~/dev/rockstor-doc> git config --list --local

Installing Sphinx

Unlike for code contributions, there is no need for a dedicated virtual machine to build the documentation. Indeed, source pages for Rockstor’s documentation are written in reStructuredText (.rst files) that can be easily edited manually to fit our needs. We then use the documentation generator Sphinx to generate the HTML content from these .rst files.

Sphinx official documentation gives guidelines for its installation on various platforms. We thus refer to their instructions on how to install Sphinx: Installing Spinx.

Once you have Sphinx installed, you’ll need 1 more Sphinx extension before you’re fully ready. The sphinxext-rediraffe extension is used to generate redirections for pages that no longer exist or have been moved. While you may not use the functionality of this extension in your page, when you execute make html to check your work, you’ll need it for make to complete successfully.

To install sphinxext-rediraffe, use this command:

you@laptop:~/dev/rockstor-doc> sudo pip3 install --user sphinxext-rediraffe

Using Sphinx as a Docker container

Sphinx can also be used as a Docker container, without needing to install it on your computer. As the base docker-sphinx image doesn’t contain the sphinxext-rediraffe extension needed to build Rockstor’s documentation, we need to use a custom Docker image. This can easily be done using a custom Dockerfile. For convenience, we provide the corresponding Docker image. Its use is documented below.

Making changes

We’ll assume you have identified an issue (eg: #1234) from the github issue tracker to work on. If you want to document something for which there is no issue, feel free to create one.

First, start with the latest documentation by rebasing your local repo’s master branch with the upstream.

you@laptop:~/dev/rockstor-doc> git checkout master
you@laptop:~/dev/rockstor-doc> git pull --rebase upstream master

Checkout a new/separate branch for your issue. For example:

you@laptop:~/dev/rockstor-doc> git checkout -b issue#1234_brief_label

You can then start making changes in this branch.

Guidelines

To keep in line with Rockstor’s goal to make its features as accessible as possible, this documentation should strive to keep non-technical users as its primary target. As such, the use of external references and links to additional documentation to provide the reader with further technical information is encouraged.

Building HTML files with Sphinx

As you edit the content in .rst files, you can periodically generate HTML files and review them in your browser. To generate or update the HTML files, use the following command:

you@laptop:~/dev/rockstor-doc> make html

If you use our docker image, you can use the following command:

you@laptop:~/dev/rockstor-doc> docker run --rm -v $PWD:/docs ghcr.io/rockstor/rockstor-doc:master make html

HTML files are generated in the _build/html directory. From a separate terminal window, you can have a simple Python webserver always serving up this content with the following command:

you@laptop:~/dev/rockstor-doc> pushd ./_build/html; python3 -m http.server 8000; popd

You can now go to http://localhost:8000 in your browser to review your changes. The webserver is to be started only once and it will continue to serve the files and changes you make to them.

After making any changes to a .rst file, run make html as shown above and refresh your browser to display your changes.

In order to check hyperlinks that are part of the changed files, it is also recommended to run the linkcheck tool that comes with Sphinx. During PR submission that link check is also run automatically. If you don’t make changes to any existing links or don’t add new ones, it is not as important. As above, with Sphinx installed you can run it directly in the documentation directory:

you@laptop:~/dev/rockstor-doc> make linkcheck

If you use our docker image, you can use the following command:

you@laptop:~/dev/rockstor-doc> docker run --rm -v $PWD:/docs ghcr.io/rockstor/rockstor-doc:master make linkcheck

If linkcheck errors occur in documents you have not modified and they are not in scope of your changes, you can probably ignore them and/or open another issue on github to address required changes (so this knowledge is not lost over time).

Submit your changes

Once you are satisfied with your changes, you can start preparing them for submission.

Add and commit your changes

First, let’s add your changes:

you@laptop:~/dev/rockstor-doc> git add new_file_added.rst existing_file.rst

Then, you can commit them. We strongly encourage you to commit changes in a certain way to help other contributors, and to keep the merge process smooth. The guidelines below pertain more to code contributions but feel free to be as perfect as you like. As a guiding principle, separate your changes into one or more logically independent commits.

you@laptop:~/dev/rockstor-doc> git commit new_file_added.rst existing_file.rst

We request that you divide a commit message into three parts. Start the message with a single line summary, about 50-70 characters in length. Add a blank line after that. If you want to add more than a summary to your commit message, describe the change in more detail in plain text format where each line is no more than 80 characters. This description should be in present tense. Below is a fictional example:

foobar functionality documentation for rockstor

This document describes foobar functionality. This feature is based on algorithm called
recursive transaction launcher to generate transactional foobars.

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch issue#1234_test
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       new file:   foobar.py
#

If you’d like credit for your patch or if you are a frequent contributor, you should add your name to the rockstor-doc AUTHORS file.

Moving pages

If your changes involve a page relocation or removal, we need to ensure any eventual external link to it remains valid and provide a valid redirection. To do so, we leverage the excellent Sphinx extension sphinxext-rediraffe. Indeed, Rediraffe can simplify the process by comparing your current Git branch to your master branch and automatically write redirections for pages that were renamed or relocated. To do so, you simply need to run the rediraffewritediff builder:

you@laptop:~/dev/rockstor-doc> sphinx-build -b rediraffewritediff . _build/rediraffe

If you use the Docker image, you must use the following command:

you@laptop:~/dev/rockstor-doc> docker run --rm -v $PWD:/docs ghcr.io/rockstor/rockstor-doc:master sphinx-build -b rediraffewritediff . _build/rediraffe

You should now see the needed redirects in redirects.txt.

Note

Make sure to commit your changes with Git before running the rediraffewritediff builder as the latter will otherwise not be able to detect your changes.

While we strive to limit such occasions, special circumstances might require the deletion of one or more pages. As sphinxext-rediraffe cannot yet automatically write a redirection for a deleted page, one needs to manually instruct it. Fortunately, this is as simple as writing a new line in redirects.txt, listing the name of the deleted page and the name of the page to which it should redirect. Below is an excerpt of redirects.txt detailing redirections for deleted files:

# Deleted files
# "deleted_file.rst" "redirection_target.rst"
"intro.rst" "index.rst"
"analytics.rst" "index.rst"
"benchmarks.rst" "index.rst"

In the example above, the now deleted files intro.rst, analytics.rst, and benchmarks.rst, are all redirected to index.rst.

Pushing changes

As you continue to work on an issue, commit and push your changes to the issue branch of your fork. You can periodically push your commits to Github with the following command:

you@laptop:~/dev/rockstor-doc> git push origin your_branch_name

Create a pull request

Once you’re finished with your work for the issue and are ready to submit, create a pull request by clicking on the pull request button on Github. This notifies the maintainers of your changes. As a best practice, only open one pull request per issue containing all the relevant changes.

To expedite the review, please follow these two tips:

• Make sure that the Sphinx make html command completes successfully without generating any error. You can also verify that all tests ran by the Github Actions complete without error or warning. In the event one of these tests fails, you can click on the Details button to inspect the Github Action’s logs and identify the problem.

• When you make a pull request, adding a “Fixes #number-of-issue” on its own line will automatically close the related issue when it gets merged. Just a nice thing to have and also provides a link to the relevant issue. See GitHub documentation for details.