Global Tools

HipChat (IM tool)

You can use HipChat to instant message individuals and groups. "Chats" are organized into rooms, by team and other interest, and by individuals.

Follow the instructions at HipChat Downloads to get set up on your desktop and mobile devices. If you do not have the app installed, you can also access HipChat via a browser.

To search for edX HipChat rooms, follow these steps.

1. In HipChat, select edX at the top left of the screen. 
   All edX rooms and people appear in an alpha-ordered list. 
2. From here, you can enter your search term, or search All, by Rooms, or by People. 
3. Double-click a room to follow the room. 

We recommend the following rooms, as well as any rooms for engineering and product teams you're on.

• edX: General company announcements, including announcements for lunch delivery.
• Docs: The room for our team.
• Product: The room for the Product team.
  • Inquire about audience-specific product rooms, as these will contain more relevant information.
• Backchannel: Random, non-work posts.
• Release: Info about the release. Very good to follow if you're working on release notes for the week.

edx.org, Edge, and Stage

You need to create an account on these three sites. You can use the same email address for all three, but they are separate sites.

• edx.org is the main edX site. Only partners can publish courses on edx.org. Anyone can find the courses listed on edx.org. 
• Edge is a smaller site. Anyone with a Studio Edge account can publish courses on Edge. Only people with the exact URL of the course can find a course on Edge.
• Stage is the internal edX testing site. 

For all three sites, you have to create an account, then request course creation rights. When you create a Studio account for each site, you automatically receive an LMS account for each site with the same credentials. (The reverse is not true, so always create accounts on the Studio site.)

1. Go to https://studio.edx.org, https://studio.edge.edx.org, or https://studio.stage.edx.org.
   Note: Because Stage is an internal site, you need the username and password for the site before you can access the site and create an account. If you don't know this username and password, contact a member of the docs team.
2. Click Sign Up, and follow the prompts to sign up.
3. Send an e-mail to support@edx.org to ask for course creation rights for each site.

Tools for Documentation

GitHub Desktop (optional)

GitHub is a website for viewing and managing Git repositories – which are just collections of files. You can access GitHub either from your web browser, or by using GitHub's desktop application, which is appropriately named "GitHub Desktop". You'll need the desktop application in order to work with branches locally.

• Follow the instructions at GitHub Desktop to install the application.

Note: You can also use GitHub from the command line.

Whether you use the GitHub Desktop application or the command line to work with git, you need a git username and access to the edx-documentation repo.

1. Go to https://github.com and select Sign up.
2. On the Join GitHub page, fill in the form, and select Create an account. Make sure to use your edX email address.
3.  When your account has been successfully created, contact edX IT and ask for access to the following repositories.
   • edx/edx-documentation
   • edx/edx-platform
   • edx-analytics-dashboard/

XCode and Make

We write documentation as reStructured Text (.rst) files using a common text editor, Sublime. We then use Make to build local HTML versions of our .rst files.

Make requires XCode. The following process installs both XCode and Make.

Note: Install GitHub first and ensure that you have access to the edx/edx-documentation repository.

1. Open the App Store, and then search for xcode.
2. Under the XCode icon, click Free, and then click Install. (Installation takes several minutes.)
3. In your Applications folder, click XCode. Ignore the window that asks if you want to create a new project or open an existing one.
4. In the menu across the top of your screen, click XCode, and then click Preferences.
5. Click the Downloads icon at the top of the dialog.
6. Under Components, locate Command Line Tools, and then click the down-arrow icon to install. 
   Alternatively, in Terminal enter xcode-select --install 
   A dialog appears asking if you would like to install the tools now. Click Install.
   A Command Line Tools License Agreement appears. Click Agree.
   The software installs. Click Done to close the dialog box and continue.
   
   

Sphinx

Sphinx converts .rst files into PDF and HTML online. This tool requires that you have already installed XCode.

In a terminal window, run the following commands from the edx-documentation directory:

1. sudo python -m ensurepip
   Note: You will be prompted for a password. Enter your machine password and then click Enter.
2. sudo pip install virtualenv
3. virtualenv venv
4. . venv/bin/activate
5. pip install -r shared/travis_requirements.txt 
   Note: Ensure that you are pointing to the correct local directory from Terminal (the Command line) so that Sphinx can successfully access the necessary themes and files.

SnagIt

The doc team uses SnagIt to edit images. You can also use SnagIt to capture images, or you can use the native image capturing capability on a Mac (CMD+SHIFT+4). If you use SnagIt to capture the image, the image opens in SnagIt automatically.

1. Download SnagIt from https://www.techsmith.com/snagit.html. You can download the trial version, then ask IT for a license. You can use the trial version for up to 15 days.
2. Follow the instructions under SnagIt Style Gallery to add SnagIt styles to your SnagIt application.
3. Follow the instructions under Text in Annotations to add the Open Sans font, which we use for image annotations.

Note: For complex changes, the team might use Photoshop. We're currently trying to use SnagIt exclusively, however. To use Photoshop, contact IT and ask for a license.

Sublime Text

You can use any text editor to edit ReStructured Text (.rst) files, but the documentation team generally uses Sublime Text. Be sure to install version 3, not version 2.

• On the Sublime Text page, download Sublime Text 3 for Mac OS X. 

Git Integration

It's convenient to use Sublime Text for writing Git commit messages and handling interactive rebases. To do this, we need to teach Git how to open and use Sublime Text. First, we'll add the subl command to the PATH, so that Git can find it. To do that, run this command:

sudo ln -s /Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl /usr/local/bin/subl

You may need to type in the password to your computer to make the command work. Once you've done so, you can verify that it worked by running

which subl

And you should see /usr/local/bin/subl as the output. Next, you need to tell Git to use the subl command as the editor. To do that, run this command:

git config --global core.editor "subl -n -w"

Now, you should be able to run any Git command that opens an editor, like "git commit" or "git rebase -i", and the editor should open in Sublime Text! 

Adding Packages to Sublime Text

Packages give Sublime Text new features that it didn't have before. For example, there are packages to integrate Sublime Text with GitHub, or to preview what your RST will look like on ReadTheDocs. If you've never added a package to Sublime Text before, you must first install Package Control, the Sublime Text package manager. To do that, follow the steps on the installation page.

Once you've installed Package Control, you should then install the following packages:

• GitGutter
  • This lets you see the way your branch differs from the master branch as you make changes. For example, if you make an addition or a deletion, a green plus sign or a red minus sign appears next to the line of text you've modified.
• Restructured Text (RST) Snippets
  • This provides handy formatting tools for RST. For example, type "h1<tab>" to format a string as a first level header, magic formatting for tables... See:  https://github.com/mgaitan/sublime-rst-completion (and scroll down to read the info).
• Wrap Plus: Wrap Lines
  • This wraps the lines at 80 characters in the current or selected text when you press COMMAND+OPTION+Q.

To install a package, follow these steps:

1. In the Sublime editor, open the Command Palette by choosing Tools -> Command Palette. Alternatively, you can press Command + Shift + P to open the Command Palette.
2. In the Command Palette, select "Package Control: Install Packages". You can type in the palette to filter this list, and press enter to select your choice. (If you don't see this selection, make sure you've already installed Package Control, and you've restarted Sublime Text.)
3. The Command Palette will show you all the packages that you can install. Select the package that you want from the list. Once again, you can type in the palette to filter the list, and press enter to select your choice.
4. After a few seconds, a message should appear in the lower-left corner saying that your package was installed. You may need to restart Sublime Text.

Adjusting the Settings for Sublime Text

Sublime Text can work better for you if you adjust some settings in the application. To do that, follow these steps:

1. Open Sublime Text
2. From the menu bar, choose Sublime Text > Preferences > Settings – User. The new Preferences.sublime-settings file opens in the editor.

3. Copy and paste the following into the file: 

   Preferences.sublime-settings

   {
     "word_wrap": true,
     "wrap_width": 80,
     "trim_trailing_white_space_on_save": true,
     "ensure_newline_at_eof_on_save": true,
     "translate_tabs_to_spaces": true
   }

   If the file already contains preferences, don't include the additional pair of braces when you copy the code block above. You'll also need to add a comma to whichever preference ends up in the middle of the file, for example: "translate_tabs_to_spaces": true,
    

4. Save the file, close the editor, and restart Sublime Text.

There are many other settings that you can adjust, if you want. To see the full list, choose Sublime Text > Preferences > Settings – Default. Note that you should not make any changes to this "default" file! Use it only as a reference, and make your changes in the "user" file.

Links

• edX GIT Repository
• GIT Cheat Sheet
• Intro to Git on Engineering Wiki