Adding and Editing Content to the GEE Documentation

How Documentation is Organized

The earthenterprise/docs/geedocs/docsrc/answer folder contains folders for each major topic. These folders contain the individual rst files for that topic.

The earthenterprise/docs/geedocs/docsrc/answer folder has the index files for all the topic folders. These index files contain a list of the rst files for each topic in the order they should be read. These index files create the browse order when users click through a topic using the Previous and Next buttons.

The earthenterprise/docs/geedocs/docsrc folder has a index.rst file that lists all the index files for major topics. This master index creates the table of contents users see when they click the Documentation link at the top of the Open GEE website.

For example, docsrc/index.rst includes fusionTutorial.rst (the index of the fusionTutorial folder), which includes all of the rst files under the fusionTutorial folder.

How to Modify or Update Documentation

• If you are modifying content to an existing file, make the changes in rst syntax.
• If you are adding a new file under existing topic, create an rst file under the topic folder and add that file where it belongs in the topic list in answer/topicName.rst, then add the content in rst syntax.

rst Syntax

rst syntax is very particular about indents and spacing, so check the examples below and ensure that your documentation is formatted correctly.

In the examples below, the first screenshot shows an example of rendered text and the second screenshot shows the rst syntax that created the rendered text.

Numbered List

Use this option when every step in a list must be completed in order. rst format will automatically number steps if they are formatted correctly. Please note that if the text of a steps continues onto a second line, it must be indented so that the text aligns with beginning of the text in the first row, not the number.

Multilevel Numbered List

Use this option when every step in a list must be completed in order, but some steps contain multiple smaller steps. rst format will automatically number one level of a list, but the second level must be numbered manually. Please note that if the text of a steps continues onto a second line, it must be indented so that the text aligns with beginning of the text in the first row, not the number. Also, you must leave a blank line between the different levels of text.

Multilevel Numbered List with Bullets

Use this option when every step in a list must be completed in order, but some steps contain options, not all of which must be used. rst format will automatically number the steps if they are formatted correctly. Please note that if the text of a step continues onto a second line, it must be indented so that the text aligns with beginning of the text in the first row, not the number. Also, you must leave a blank line between the different levels of text.

Bulleted List

Use this option when you have an unordered list, such as a list of examples. Please note that if the text of a step continues onto a second line, it must be indented so that the text aligns with beginning of the text in the first row, not the number.

Multilevel Bulleted List

Use this option when you have an unordered list, such as a list of examples, and some items have sub-items. Please note that if the text of a step continues onto a second line, it must be indented so that the text aligns with beginning of the text in the first row, not the number. Also, you must leave a blank line between the different levels of text.

Bold Text

Use bold text when you are referring to an action performed by the user. Bold button names, field names, menu commands, and non-code text for users to enter.

Italic Text

Use italic text when you wish to emphasize something. Some users find italics difficult to read, so use italics sparingly.

Code-Formatted Text

Use code-formatted text when you are listing a file path, file name, or command for users to enter. There are several different ways to format code, depending on how it is presented.

• Inline code appears in the middle of a sentence.

  

  

• Single-line code appears on its own line. You must leave empty lines before and after the code.

  

  

• Multi-line code requires multiple lines. To accomplish this, you must place the text inside a code block. You must leave empty lines before and after the block. To date, Open GEE has used several different types of code blocks:

  • Bash code blocks specify Bash commands. Use this when you are entering a Bash command.

    

    

  • HTML code blocks specify HTML code. Use this when you are entering HTML.

    

    

  • Perl code blocks specify Perl code. Use this when you are entering Perl commands.

    

    

  • XML code blocks specify XML code. Use this when you are entering XML.

    

    

  • Unspecified code blocks do not specify a code type. When in doubt, use an unspecified code block.

    

    

  More information on code blocks can be found here.

Add an Image

Images are most often screenshots of steps in the instructions. Inserting images is a three-step process.

1. First, add the image to the appropriate folder. Images are kept in the earthenterprise/docs/geedocs/docsrc/art folder, with subfolders for the topics.

2. Next, enter the image details in a directive at the end of the document: an image alias, its path, and dimensions if you wish to resize the image.

   

3. Last, enter the image alias in the appropriate location in the documentation. If the image will be on its own line (rather than in a line with text), remember to leave empty lines before and after it.

   

   

Tables

Tables must be formatted carefully, with close attention paid to indents and spacing. Tables should not have a title if they would have the same title as the section they occur in.

External Hyperlinks

External hyperlinks follow a standard format, requiring link text and a URL.

Link to a Documentation Page

You can insert a cross-reference to another page in Open GEE's documentation. There are two formats you can use:

• If you wish to use the page title as the link text:

  

  

• If you wish to use your own text as the link text:

  

  

Link to a Specific Location on a Documentation Page

You may also insert a cross-reference to a specific location on another page in Open GEE's documentation. It is a two-step process.

1. First, you must place a label at the destination location.

   

2. Next, you insert the cross-reference.

   

Create a Heading

Headings in the documentation typically take two forms. There are main headings, which are title case, and sub-headings, which are sentence case. Both are tagged the same way.

• Heading

  

  

• Sub-heading

  

  

Add a Note, Tip or Warning

Notes, tips, and warnings are informational messages that appear in a window on the screen. Use them when you wish to call particular attention to something.

• Add a Note

  

  

• Add a Tip

  

  

• Add a Warning

  

  

Add a Page Title

Page titles are displayed at the top of each page. They should be used as a short summary of the page contents. As well, if you are creating a new page, the file name should be based on the page title.

Add an Index Entry

Topics must be manually tagged to appear in the index. Typically, only rubric topics appear in the index and entries are limited to nouns.

Build the Finished Documentation

After you have edited rst files, you must generate the html files that are published on opengee.org. For instructions on building the html files, click here.