Difference between revisions of "Activities/Help/Contribute"

From Sugar Labs
Jump to navigation Jump to search
(Created page with "{{Under construction|--~~~ Target completion mid December 2013.}}")
 
(This page aims to inform anyone interested in contributing to Sugar documentation, Help 18 and beyond.)
Line 1: Line 1:
 
{{Under construction|--[[User:Inkyfingers|Inkyfingers]] ([[User talk:Inkyfingers|talk]])
 
{{Under construction|--[[User:Inkyfingers|Inkyfingers]] ([[User talk:Inkyfingers|talk]])
 
Target completion mid December 2013.}}
 
Target completion mid December 2013.}}
 +
 +
This page aims to inform anyone interested in contributing to Sugar documentation, Help 18 and beyond.
 +
 +
This page acts as a "Landing page" for those who have read "How to edit Help and contribute" in Help 17, and to encourage others to test it.
 +
 +
Any updates to the technical contents of that page will be announced here. Please see [[#Known issues]].
 +
 +
== History ==
 +
 +
Based on IAEP community edits made in 2012, a new Help 16 Activity was created.
 +
 +
Previous recent history is here: http://wiki.laptop.org/go/Help_Activity_refresh/0.98
 +
 +
== Localization, other tools ==
 +
 +
Primary reference http://translate.sugarlabs.org/.
 +
 +
== Contact ==
 +
 +
Anybody interested in contributing can send a mail to sugar-devel mailing list http://lists.sugarlabs.org/listinfo/sugar-devel or to gonzalo at laptop dot org
 +
 +
Users actively involved, who are prepared to review the work of contributors:
 +
 +
[[User:Inkyfingers]]
 +
 +
Please add you name ...
 +
 +
==Wish list for new documentation==
 +
 +
Compare with the old content, and check if something is missing http://dev.laptop.org/~gonzalo/old_help/XO_Introduction.html
 +
 +
Keyboard shortcuts
 +
 +
Please add any item you see missing.
 +
 +
Please add your ideas
 +
 +
This version of Help allows us to have an open mind about how Help documentation evolves, depending on the content provided by contributors.
 +
 +
=== New to Sugar pages===
 +
 +
Entry level contributions are particularly welcome.
 +
 +
There is the possibility of modifying some pages, so that towards the top of page one finds "entry level" links to compact topics like :
 +
 +
* navigation
 +
* function keys
 +
* frame
 +
* add features and tools, which are needed for competent use of Sugar.
 +
 +
Please add your ideas
 +
 +
== Collaboration ==
 +
 +
It would be good to find a model for collaboration. It might be possible within the Sugarlabs system to upload a help_page.rst for multiple editors.
 +
 +
Any suggestions welcome for a repository for "Documentation - work in progress".
 +
 +
== Sugar features page ==
 +
 +
A page was produced quickly before Help 17 was published. This is ripe for improvement.
 +
 +
The current content is View source and Say selected text.
 +
 +
Please add undocumented features.
 +
 +
== How does this effort support Mallard? ==
 +
 +
Please see also [[Documentation_Team/Notes/1.0]]
 +
 +
== How to get freshest Help sources ==
 +
 +
To see work in progress since Help 17 went to press:
 +
 +
This command:
 +
git clone gitorious@git.sugarlabs.org:help/mainline.git
 +
you will get the Help Activity _with_ the sources included.
 +
 +
You can install it in your development environment doing:
 +
 +
cd mainline
 +
./setup.py dev
 +
(if you have the activity already installed, uninstall it first)
 +
 +
Now you can modify any .rst file in source directory or the images in the images directory,
 +
and to create the html files, you only need do:
 +
 +
make html
 +
 +
* In Sugar
 +
You don’t need to restart the activity to see the changes, can do click
 +
with the secondary button, and select reload.
 +
 +
* In any other Linux environment
 +
The output of make html is in /mainline/html, and is opened by opening
 +
index.html in a browser, it is easy to see the changes as you work.
 +
 +
== Further reading ==
 +
 +
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/.
 +
 +
== Known issues ==
 +
 +
=== Not fully documented ===
 +
 +
a. If work you have done seems to have corrupted Help,
 +
 +
b. or in the event you wish to make changes to the index, over and above, adding a new line to the bottom a table of contents as described in the tutorials,
 +
 +
you may delete all the output files, that is, ``~/mainline/html/`` and ``~/mainline/doctrees/``. They will be regenerated by ``make html``.
 +
 +
=== Reconfigure Help to show View source ===
 +
 +
In Sugar as we already have a View source button in the frame.
 +
 +
If you are working with the Help software in a browser, you can add a *View source* button, which will appear in the navigation panel. 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.
 +
 +
== To add, existing Help index for reference ==
 +
...

Revision as of 07:35, 11 December 2013

Warning.png
Under construction
This page is under active construction at this time. Please check back shortly for updated information.
--Inkyfingers (talk) Target completion mid December 2013.

This page aims to inform anyone interested in contributing to Sugar documentation, Help 18 and beyond.

This page acts as a "Landing page" for those who have read "How to edit Help and contribute" in Help 17, and to encourage others to test it.

Any updates to the technical contents of that page will be announced here. Please see #Known issues.

History

Based on IAEP community edits made in 2012, a new Help 16 Activity was created.

Previous recent history is here: http://wiki.laptop.org/go/Help_Activity_refresh/0.98

Localization, other tools

Primary reference http://translate.sugarlabs.org/.

Contact

Anybody interested in contributing can send a mail to sugar-devel mailing list http://lists.sugarlabs.org/listinfo/sugar-devel or to gonzalo at laptop dot org

Users actively involved, who are prepared to review the work of contributors:

User:Inkyfingers

Please add you name ...

Wish list for new documentation

Compare with the old content, and check if something is missing http://dev.laptop.org/~gonzalo/old_help/XO_Introduction.html

Keyboard shortcuts

Please add any item you see missing.

Please add your ideas

This version of Help allows us to have an open mind about how Help documentation evolves, depending on the content provided by contributors.

New to Sugar pages

Entry level contributions are particularly welcome.

There is the possibility of modifying some pages, so that towards the top of page one finds "entry level" links to compact topics like :

  • navigation
  • function keys
  • frame
  • add features and tools, which are needed for competent use of Sugar.

Please add your ideas

Collaboration

It would be good to find a model for collaboration. It might be possible within the Sugarlabs system to upload a help_page.rst for multiple editors.

Any suggestions welcome for a repository for "Documentation - work in progress".

Sugar features page

A page was produced quickly before Help 17 was published. This is ripe for improvement.

The current content is View source and Say selected text.

Please add undocumented features.

How does this effort support Mallard?

Please see also Documentation_Team/Notes/1.0

How to get freshest Help sources

To see work in progress since Help 17 went to press:

This command: 

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

you will get the Help Activity _with_ the sources included.

You can install it in your development environment doing: 

cd mainline
./setup.py dev

(if you have the activity already installed, uninstall it first)

Now you can modify any .rst file in source directory or the images in the images directory, and to create the html files, you only need do: 

make html
  • In Sugar

You don’t need to restart the activity to see the changes, can do click with the secondary button, and select reload.

  • In any other Linux environment

The output of make html is in /mainline/html, and is opened by opening index.html in a browser, it is easy to see the changes as you work.

Further reading

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/.

Known issues

Not fully documented

a. If work you have done seems to have corrupted Help,

b. or in the event you wish to make changes to the index, over and above, adding a new line to the bottom a table of contents as described in the tutorials,

you may delete all the output files, that is, ``~/mainline/html/`` and ``~/mainline/doctrees/``. They will be regenerated by ``make html``.

Reconfigure Help to show View source

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

If you are working with the Help software in a browser, you can add a *View source* button, which will appear in the navigation panel. 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.

To add, existing Help index for reference

...

Retrieved from "https://wiki.sugarlabs.org/index.php?title=Activities/Help/Contribute&oldid=90823"