path: root/source/how_to_help.rst

===============================
How to edit Help and contribute
===============================

.. Note::

   *27 November 2013. Draft version for review.*

   *I have checked the tutorials, but would appreciate if they were independently tested.*

   *Corrections, omissions, and feedback most welcome, iain at browndouglas dot plus dot com.*


Help displays documentation for Sugar and the XO laptop. Help contains a :ref:`View source` button.

This version of Help contains all the source files and images. These files can be edited within Help, and displayed. Help is now capable of producing new pages for Help, or making completely fresh documentation.

Help allows internationalization of the content, by {reference required} {To what extent can this page encourage users to get involved with that?}

This page aims to show how to write attractive documentation, which, if users share their work, could be used to improve Help. To contribute you only need to:

* Create a development environment
* Make changes
* Contribute the changes

Create a development environment
--------------------------------

XO Help.xo 17 already includes the source files ready to use.

Alternatively, you can use git to get Help Activity with the most recent sources included. If you have the Activity Help already installed, uninstall it first. Generally an Activity is uninstalled from the F3, Home View, List, by selecting the Activity, and press Erase. Where Erase is not available, you need to delete ``Help.activity`` from the folder ``~/Activities``.

The following guide assumes you ``git clone`` from your home directory. This command will collect all the required resources.

::

 git clone gitorious@git.sugarlabs.org:help/mainline.git

You can install it in your development environment doing: :: 

 cd mainline
 ./setup.py dev

You can modify any .rst file in ~/mainline/source/ directory or the images in the ~/mainline/source/images/ directory.

To create the HTML files. You only need do: ::

 cd mainline
 make html

If you see an error indicating that HTML cannot be built, the most likely cause is that ``python-sphinx`` is missing.

To fix this, in Terminal Activity (or any terminal emulator) as root, ::

 yum install python-sphinx

or in Debian or Ubuntu derivatives, ::

 apt-get install python-sphinx

In **Sugar** you don't need restart Help to see the changes after running ``make html``, you just click with the secondary mouse button, and select reload.

In any other Linux environment the output of ``make html`` is in ``~/mainline/html``, and is displayed by opening ``~/mainline/html/index.html`` in a browser.

What if I break Help?
:::::::::::::::::::::

In Sugar you cannot break Help. If you start to follow these instructions and get lost or make a mistake, and Help will not display correctly, you should not worry.

You should simply visit  `ASLO <http://activities.sugarlabs.org>`_ with Browse. Search for Help, and download and install a new copy of XO Help.

Alternatively, experienced users might make a backup .xo before starting to work by doing: ::

 ./setup.py dist_xo

This will create a directory dist and inside, an .xo file.

.. _Orientation:

Orientation
:::::::::::

**Source**

The two source folders we look at are filled initially by the download of Help.

The directory ``~/mainline/source/`` contains the text files we will be altering in this guide.

The directory ``~/mainline/images/`` contains all the images that are used on the various pages of Help. You can add image files to this folder, and if they are linked into documents, they will display in the *output* of the command ``make html``. 

In Sugar you have the ability to inspect the source files safely, using the :ref:`View source` button on the Help icon in the Frame.

The key page in navigating Help is the Index or contents page. In the ``~/mainline/source/`` folder, `index.rst` is the text document which automatically provides links to all other pages in the source folder.

**Output**

The pages displayed in Help are the *output* of the command ``make html``. The files are all in the folder ``~/mainline/html/``.

Depending on the setup of your installation there may be a number of other folders present in the ``~/mainline/html/`` folder (for instance ``_sources``, ``_static``, and ``_images``). These are also *output files*, they could be regarded as hidden folders, and should not be edited.

**Navigation**

In Browse and some other browsers if you type ::

 file:///

in the address bar, you will be browsing the root of your file system.

Now move progressively through ::

 file:///home

 file:///home/your-username

 file:///home/your-username/mainline

 file:///home/your-username/mainline/source

You are now able to open and inspect any of the *source_files.rst* safely.

We can back off again and reach ::

 file:///home/your-username/mainline/html

and then select and display any of the output HTML files.

Make changes
------------

You can just write a page in simple text, perhaps with some explanatory pictures or screen-shots. Screen-shots are made in Sugar from the keyboard, by pressing the "Alt" key and 1.
The page :doc:`/restructuredtext` gives some guidance on the features of the markup language we use. Do not be concerned with complex features, plain, simply written text will be of most use to new learners.

You will have your own ideas about what you would like to change and contribute. When you explain anything, which you have struggled to learn, it is likely to be of use to others. Seeing your work published gives quite a buzz!

Here are a few exercises, which demonstrate making changes, and making pages.

Tutorial 1 - Make a page
::::::::::::::::::::::::

We are going to make a fresh page in reStructuredText. It will not at first be connected to the index, or contents page, of Help.

1. Open a new file in any text editor.

2. Save the file with the name ``my_first.rst`` in ~/mainline/source . (Here we have called ``/home/your-username/mainline/source`` by the shorter, ``~/mainline/source``). Type some text onto the page. In order to give the page a title we put a line of "=" "equal" signs above and below the title like this. Leave a line of white space, then type some text. This is an example:

::

 =============
 My first page
 =============

 I am going to learn to write a Help page.

3. Now we want to convert our little page of text into an attractive page of Help. Open Terminal Activity (or any terminal emulator) and type,

::

 cd mainline
 make html

4. There will be about ten lines of output, there will be mention of errors. Read the error trace, expect to see an error line like the one below, but the final two lines here report a success.

::

 ~/mainline/source/my_first.rst:: WARNING: document isn't included in any toctree
 ...
 build succeeded, 3 warnings.
 Build finished. The HTML pages are in ./html.

The warning, "WARNING: document isn't included in any toctree" is telling us the document is not linked into the Help index yet.

Tutorial 2 will fix this. It does exist and you could see what it looks like if you can find it as described above with a browser in ``~/mainline/html``.

Tutorial 2 - Link page to index
:::::::::::::::::::::::::::::::

1. Backup your index file. Open Terminal Activity (or any terminal emulator) and type,

::

 cd mainline
 cd source
 cp index.rst index.rst.ori

Above, we have changed directory into mainline, changed directory into source, and copied ``index.rst`` to a new file named ``index.rst.ori``

2. Before proceeding make sure you are familiar with how to restore your index from the backup, in case you damage your Help index.

3. Open ``~/mainline/source/index.rst`` with a text editor. Notice the line spacing (lines of white space especially) and indents. They are very important to maintain.

4. Scroll down ``index.rst`` right to the bottom of the page. Put the cursor at the front of the last line. Using the arrow keys you will see that the indent is 4 "spaces", it is not "Tab".

5. Put the cursor at the end of the last line. Press *Enter*, press space bar 4 times, and enter the file name you used above ``my_page.rst``. Use "Enter" and the space bar so that  you exactly copy the indentation, and line spacing as used in the other entries.

6. Double check your changes to ``index.rst`` and save your changes. 

7. Now we want to convert our index into HTML. Open Terminal Activity (or any terminal emulator) and type,

::

 cd mainline
 make html

8. The newly changed index page will now display in Help, or in your browser, once you reload the page. In Sugar you click with the secondary button, and select reload, or in a browser pointing to ``~/mainline/html/index.html`` press the reload button. In the index, or contents page, the link to your new page can be clicked to open your page "my_page.html"

Tutorial 3 - Adding an image
::::::::::::::::::::::::::::

1. Open your existing page in any text editor, or create and "Title" a new page, and add it to the index.

2. An image which is already in ``~/mainline/images/`` can be included by typing this on to your page.

::

 .. image :: ../images/Help.png

The "reference line" above needs a line of white space, above and below it.

3. You can add an image file in .jpg or .png format to ``~/mainline/images/``. It is best if the image does not exceed 800 pixels in width. It can be difficult to read around tall images. For this reason screen-shots 600 pixels in width may be a good compromise if the content is simple.

4. If you add an image file ``my_image.png``, made in, say, Paint to ``~/mainline/images/``, then you link it into your page with:

::

 .. image :: ../images/my_image.png

5. Now we want to convert our page with an image into HTML. Open Terminal Activity (or any terminal emulator) and type,

::

 cd mainline
 make html

6. The newly changed page will now display in Help, or in your browser, once you reload the page.

Tutorial 4 - Write or improve a Help page
:::::::::::::::::::::::::::::::::::::::::

Decide whether you want to make a page from a fresh start, you could just start writing on a subject you know about. Alternatively experiment with improving an existing page. You could work from the text of an existing page (it might be this page) or a more simple page.

1. Open ``~/mainline/source/index.rst``.

2. Put the cursor at the end of the last line. Press *Enter*, press space bar 4 times, and enter a new file name, perhaps, ``my_second.rst``. Use "Enter" and the space bar so that you exactly copy the indentation, and line spacing as used in the other entries.

3. Double check your changes to ``index.rst`` and save your changes.

4. Open a new file in any text editor.

5. Save the page as the new file name chosen above, perhaps, ``my_second.rst``.

6. Type in a title like this:

::

 ==================
 How I changed Help
 ==================

7. Enter your text, and save your changes.


8. Now we want to convert our page into HTML. Open Terminal Activity (or any terminal emulator) and type,

::

 cd mainline
 make html

9. The newly generated page will now display in Help, or in your browser, once you reload the page.

10. You can now go back to your page, and improve it.

11. Again, write the changes to HTML version, with:

::

 cd mainline
 make html

12. You have now written your first improved page for the Activity Help. We would love it if you could share it with the Sugar community!

.. _Contribute:

Contribute
----------

Once you are familiar with editing, adding a page, and making or improving a Help page, you could make a page with the intention of having it published in the next version of Help.

You might write a tutorial on a subject you know about.

In the next version of Activity Help, better "New to Sugar" pages might be included at the beginning of Help, as a quick introduction for new Sugar learners. Contributions to be considered would be welcome.

Some Activities have no easy to find instructions. If you can write even a very short introduction, it could be very useful for other Sugar learners.

The Sugarlabs wiki page http://wiki.sugarlabs.org/go/Activities/Help/Help_17 might have some ideas on pages, which have been requested, or which others are working on and might appreciate collaboration.

What to do with your finished work
::::::::::::::::::::::::::::::::::

First of all you might briefly contact gonzalo at laptop dot org by e-mail to tell him what you would like to contribute. If you write a new page , you can send him the page (as my_page.rst) as an attachment to an e-mail explaining briefly what is attached. If new images are linked into the page, send them too.

If you have improved a page, the preferred method is to submit it as a "patch".

Tutorial 5 - generate a patch
:::::::::::::::::::::::::::::

1. Let's say you decide to work on the Help page, "Switching Activities". You might back up that page before you start. Open Terminal Activity (or any terminal emulator) and type,

::

 cd mainline
 cd source
 cp switching_activities.rst switching_activities.rst.ori

Above, we have changed directory into mainline, changed directory into source, and copied ``switching_activities.rst`` to a new file named ``switching_activities.rst.ori``

2. Make your changes to ``switching_activities.rst``. Save your changes regularly, and check by running the ``make html`` command that the page displays nicely. Once you are happy with your work, you can generate a patch like this:

::

 cd mainline
 cd source
 diff -u switching_activities.rst.ori switching_activities.rst > switching_activities.patch

3. The patch can now be sent as an e-mail attachment.

4. For more information, in Terminal Activity (or any terminal emulator) type,

::

 man diff

and

::

 man patch


Reconfigure Help to show View source
------------------------------------

In Sugar as we already have a :ref:`View source` button in the frame.

If you are working with this software in a browser, you can add a *View source* button, which will appear in the navigation panel on the left. You need to alter three lines in ``~/mainline/source/conf.py``. Each of the entries listed below comprise a comment line, starting with a"#" followed by the code line. Find each pair of lines in ``conf.py`` and change the value in the code line like this. ::


 # Custom sidebar templates, maps document names to template names. ## Edit: Sugar default is without 'sourcelink.html'
 html_sidebars = {'**':['localtoc.html', 'sourcelink.html']}

 # If true, links to the reST sources are added to the pages. ##Edit: Sugar default is False
 html_show_sourcelink = True

 # Do not copy .rst files ##Edit: Sugar default is False
 html_copy_source = True

A disadvantage of doing this is that extra folders are created, that might be confusing at first, and the duplication of files can make it difficult to correct certain mistakes. The command ``make html`` also takes longer to run. It is recommend not to make these changes before you are confident navigating the source and HTML folders.

.. _Further reading:

Further reading
---------------

|more| For more complete help on reStructuredText:

.. |more| image:: ../images/more.png

Quick reStructuredText, http://docutils.sourceforge.net/docs/user/rst/quickref.html, is a cheat-sheet for reStructuredText.

"reStructuredText Directives" http://docutils.sourceforge.net/docs/ref/rst/directives.html by David Goodger, March 2013.

Sphinx reStructuredText Primer, http://sphinx-doc.org/rest.html, a brief introduction to reStructuredText concepts and syntax.

Sphinx home page, http://sphinx-doc.org/index.html.

Another tutorial, http://matplotlib.org/sampledoc/.