sugarlabs/sugar-docs

Documentation for Contributors and Developers

Sugar Labs

Welcome to documentation for contributors and developers.

Getting started

• Code of Conduct
• How can I help?
• Contribute code
• Programming Languages
• Contact

Design

• Human Interface Guidelines
• Sugar Iconify

Sugar Desktop

• Setup a development environment
• Write your own Sugar desktop activity
• Python code style
• Memory leaks
• GTK 3 Porting Guide
• Python 3 Porting Guide
• Python Coverage Guide
• Guide to installing Sugar on Debian

Sugar Web

• Write your own Sugar web activity
• Architecture
• JavaScript style
• Web code style
• Components showcase

Sugar Android

• Sugarizer
• Web activity

Documentation

• Improving this documentation

sugar-docs's Issues

what-can-i-do task lists brief, yet we have excessive duplication and redundancy

What a wonderful problem to have! We have several lists of tasks that can be done;

• project ideas for Outreachy engagement,
• project ideas for Google Summer of Code engagement,
• release engineer's feature tracking, apparently unmaintained after position rotation,
• design team user experience proposals, apparently unmaintained after design team silence,
• trac instance view tickets list of open bugs, many of which are abandoned, and the instance is protected against new users,
• next release feature list, currently empty but likely to grow.

Have I missed any? If I could list so many, there's bound to be another list somewhere I don't know about. 😁

These lists might be combined in some fashion, deprecated, and then referenced on what-can-i-do here.

Explain how to document an activity's codebase

The developer docs should provide

• a guide to an activity's codebase should best be documented;
• examples of 3 activities with great code documentation;

See 2016-June [Sugar-devel] What to use for documenting new sugar activities? thread for discussion

Port to GTK+ 3 Guide

Migrate from Wiki.
https://wiki.sugarlabs.org/go/Features/GTK3/Porting

SugarSocial

What are the features you want to add to sugarsocial?

building sugar-docs without sugar-build?

14:22 < Pro-Panda> Hi walterbender, I want to run the developer docs website locally. I read this https://developer.sugarlabs.org/docs.md.html, but I can't figugre how to use the sugar-build and run 'docs'

• We have several ways of setting up development environments that do not use sugar-build in any way and
• We have removed mention of the sugar-build approach to setting up a development environment

So, some documentation about how to run local tests of changes to the documents might be prudent.

There are many tools for converting Markdown to HTML, but subtle difficulties can arise due to differences amongst Markdown dialects, amongst toolsets, and from inconsistencies in how paths are handled from one context to another.

How is the Markdown in this the https://github.com/sugarlabs/sugar-docs repo converted into the HTML displayed at http://developer.sugarlabs.org ?

Is https://pypi.python.org/pypi/Markdown used? Are there known and documented differences in how it handles things compared to https://github.com/github/markup to which we can make reference?

Can we describe some variant of that process here in our documentation so that people can review their changes before submitting them?

If we are using sugar-build to generate the HTML served at developer.sugarlabs.org then we might either want to take a step back and keep some mention of sugar-build in these documents, or consider whether we can sustain the way that Markdown-to-HTML transformation is being effected in production and whether that needs a change.

It might be sufficient to suggest a developer push to their own github fork and rely on Github to render that, pursuing differences in the way Markdown is rendered between the two environments on a case-by-case basis as bugs. If so, we should edit https://github.com/sugarlabs/sugar-docs/docs.md to reflect that.

Sorry, this is documentation about development of documentation so if I'm confused or am confusing anyone else, my apologies.

Missing readme.md in repos

The following repos doesn't have a readme.md file.

get-books-activity
activity-i-can-read
jukebox-activity
browse-activity
maze-activity
record-activity
AEIOU
clipart
story
imageviewer-activity
iknowmyabcs
biorhythm
AnalyzeJournal
physics
colordeducto (README.txt and not README.md)
fractionbounce
sugar-datastore
sugar-toolkit
sugar-web
Buttons-and-Scissors
paint-activity
activity-abacus
finance-activity
activity-turtleart-extras
activity-turtle-confusion
activity-turtle-flags
moon-activity
xocolors
yupana
napier
pukllanapac
reflection
paths
ruler
locosugar
lettermatch
deducto (text file and not markdown)
convert
recall
SocialCalc
Bridge
sugar-launcher-applet
nutrition
cedit-activity
Frotz
GTranslator
pymusicblocks
spanish-guarani
pyeyes-activity
reversi-activity
devtutor-activity
guido-van-robot-activity
collabedit
pydebug-activity
blender-activity
teachteacher-activity
Bounce
DrGeo
MathGraph32
JClic
XaoS
Kiwix
pocket-lrad-activity
HacketyHack
tuxmath-activity
Time-Line
showntell-activity
riverhex-activity
Constellationsflashcards
blocku
Sugarizador
XOlympics
ShowJPEG
pilas-activity
VncLauncher
supervampireninjazero-activity
Gmail
Sugarizehelp
cavestory
agubrowser-activity
Snow
distance-activity
letters
sugar-web-template
cookiesearch
slideruler
olpc-os-builder
sugar-continuous
sugar-gitbot
sugar-base
hello-world-fork
sugar-web-test

Some links not present

I found few of the link on contribution.md file not working.

• https://github.com/sugarlabs/sugar-docs/blob/master/web-activity.md.html
• https://github.com/sugarlabs/sugar-docs/blob/master/desktop-activity.md.html
• http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages

Is docs.md still current?

Is https://github.com/sugarlabs/sugar-docs/blob/master/docs.md still current?

I suggest transitioning the website to http://grow.io - its python and has been l10n

And then we can get away from these weird "page.md.html" URLs :)

broken formatting in dev-environment.md

In adding fields, the heading style associated with === no longer seems to be applied properly (worked fine in my previewer but not on github itself). The impacted lines are:

Setup a development environment - packaged style

and

Setup a development environment - native style

Github Action Bot Prosebot

GitHub Bots Integration
Check for Spelling Errors in the Docs
Check For Grammatical errors
Provide an easy way for documentation
Analyze prose , text in markdown files

Integrate User:Jlew/XO_Workflow info

https://wiki.sugarlabs.org/go/User:Jlew/XO_Workflow has some good tips

No Template for writing an issue in contributing.md

What
No Template for writing an issue in contributing.md file.

Why
As a new user, I can't find any template on how to write/report an issue, in order to follow best practices for documenting an issue.

Link(s) to documentation/specs
https://github.com/sugarlabs/sugar-docs/blob/master/src/contributing.md?fbclid=IwAR09iMb540v7ZY41-LYLR7BkVuCyZsslAW6__1QJ1H-gOI2NahywNsb1gHw#workflow

Notes
The benefit of having a template of writing an issue is that it ensures everyone involved will have a shared understanding of the tasks/requirements. It will give a sense of structure on how to report an issue, avoid any ambiguity, and make it easier for others to recreate the issue to provide better assistance/feedback.

link not working

The hyperlink to the guide in this section is not working.
https://github.com/sugarlabs/sugar-docs/blob/master/src/how-can-i-help.md#-coding-documentation-and-quality-assurance
You can port activities which are in GTK+ 2 to GTK+ 3, using the guide.
You can port activities which are in Python 2 to Python 3, using the guide.
It is showing 404 page not found error.
The old links are not working please replace them to new ones.

desktop-activity code not being displayed

File: desktop-activity

Type: Bug

Details: The code in desktop-activity is not being displayed on the webpage. It's missing the opening and closing " ` "(grave accent) to highlight code in markdown.
The image "activity-helloworld.svg" is also not being displayed on the webpage. It is being displayed in Github Preview and I can't find the cause of the discrepancy.

Tested on: Firefox 58, Ubuntu 16.04

what-can-i-do lists outdated 'top ten tickets'

The What can I do? page links to the "Top ten tickets for the week", which seems to not be maintained.

I propose its removal to prevent confusion for new wannabe contributors (heh, guess how I found this issue ><). I will submit a PR for this shortly.

Inaccessible Link

Under Sugar Web, Components Documentation links to https://developer.sugarlabs.org/sugar-web/README.md.html, which generates an ERROR 404 NOT FOUND.
nginx/1.10.1

Showing 'Internal Error' in Get Involved Link on Sugarlabs wiki page

Link to regenerate error:
https://wiki.sugarlabs.org/go/Sugar_Labs/Getting_Involved

Preview of Error:

Provide communication channel link for contributors.

The link to the communication channel ( whether gitter or IRC) will be important for beginners who want to contribute to the organization and want some help from the current mentors and other contributors.

Accessibility; keyboard navigation does not work

When opening any page on developer.sugarlabs.org, the keyboard navigation feature does not work. This does not comply with accessibility guidelines.

Please fix the generated HTML or CSS so that keyboard scrolling is available after page load.

Occurs on Browse-200, Chromium-53, Firefox-52, and most other browsers.

Does not affect mouse-wheel or touchscreen scrolling.

Workaround is to click in the body of the page first. Keys are page down, page up, arrow down, arrow up, home, end, and space bar.

Reproducer:

• using a desktop or laptop computer, open http://developer.sugarlabs.org/
• click on ''Contribute code'' and wait for page to load,
• press page down key on keyboard.

Expected result:

• the content shall scroll,

Observed result:

• the key is ignored.

Add section about testing

http://lists.sugarlabs.org/archive/sugar-devel/2014-January/046700.html explains how to set up test in an Activity, and this should be integrated into the developer documentation

add discussion of repository field in activity.info file

When describing the contents of the activity.info file, we neglect to mention the repository field. (Would be good to add this field to the hello-world activity.info file as well.)

sugar-build still mentioned in sugar-docs/src/desktop-activity.md

As per discussions in, for instance, #132 and #95, sugar-build is no longer maintained, so reference to it in developer docs should probably be removed.

Improve osbuild shell docs

See confusion at travis-ci/travis-ci#6152 (comment) about this

sugarlabs.github.io ???

The reason I have not migrated Music Blocks to the sugarlabs project on github is due to the fact that we have not yet set up sugarlabs.github,io.

The basic idea would be to write some scripts to do the following:

(1) Build a landing a page for sugarlabs.github.io
(2) The content of this page should be driven by the README.md files on the various Sugar Labs repositories;
(3) Artwork can be extracted from the activity icons (and screenshots);
(4) This page must be generated via a script so it is "maintainable"
(5) Set up a webhook so that the script can be triggered whenever a repo is changed.

We can also define a heuristic to determine which activities can be run from sugarlabs.github.io, e.g. Music Blocks.

But essentially, it will be an auto-generated help site for Sugar Labs based on repo content. (We have a separate project for migrating the wiki help content into the individual repos. We could also write a script to auto-populate the Sugar Help activity, but again that is a separate project.)

Add support for markdown tables

When we add tables we have to use HTML instead of markdown. #135 is an example.

How it works now; the markdown source is converted by a rebuilder. The converter is an old version of docker and depends on an old version of showdown.

How it might work instead; the converter might be updated to the latest version of docker which no longer uses showdown.

See also #132.

coding style for JavaScript

we have a coding style guide for Python: https://github.com/sugarlabs/sugar-docs/blob/master/src/python-style.md but not for JavaScript.

Improve git ignore guidance

Per @quozl in sugarlabs/flappy-birds-activity#1 (comment) the py docs should say,

• Updates docs with a note like,

Always remember to use a pristine clean git repo when creating the bundle; nothing pending listed in git status, because the .gitignore file is not used when you run python setup.py dist_xo

• Update docs with a guide to setting up a good .gitignore and include this in the hello-world repo
• Improve python setup.py dist_xo to use .gitignore

Import Sugar_iconify.py docs

https://wiki.sugarlabs.org/go/Sugar_iconify

Port help.sl.o contents

https://help.sugarlabs.org/en/index.html has great development docs that should be ported here

Broken link

Second point in port to python 3 guide.
Use the Python 3 version of Sugar Toolkit GTK+ 3 (currently under development, here).
On clicking on here results in page not found.

Improve Python 3 porting guide

After running 2to3, there is no other guidance. There may be common patterns of change that are required. These can be added to the guide.

@Aniket21mathur, as an opportunity.

Feat: Setup PR and Issue templates

Description:

• Currently any new user who comes up to this repository and reports a new issue ticket, we don't have a template. For a better contributor experience, also there is no template for PR while raising one.

Potential Solution:

• We can create a markdown file for the same.

Screenshots:

Helpful links:

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository

For experts instructions still attracts people who aren't experts

@iamutkarshtiwari reported difficulty following the native build instructions on Ubuntu 16.04;

• did not know apt requires root; add sudo prefix,
• did not know that apt build-dep requires deb-src lines added to /etc/apt/sources.list; add a reference to Ubuntu or Debian documentation or man sources.list.

It may be better to remove this section rather than have it duplicate documentation by GNU, Ubuntu, Debian, or Fedora.

Activity Port to Python 3 Checklist

We need a "Activity Port to Python 3" checklist , for example;

• install the Python 3 Sugar Toolkit for GTK+ 3,
• change sugar-activity to sugar-activity3 in activity/activity.info,
• change any #! from python2 to python3,
• port to Python 3,
• run flake8 and fix things,
• test.

cannot serve locally

i am unable to serve sugarlabs.org locally using bundle exec jekyll serve --incremental

it would be very much appreciated if anyone could help me out. " i am working on slow loading(speed) issue of the website"

P.S. its not the apt place to ask such a problem but i was unable to find any links to gitter or any other IRC

Redesign the Documentation

The Webpage looks too abstract it should be redesigned

Explain MIME types for object chooser dialog

Yash asked on sugar-devel,

what mime type should I use in the object chooser dialog for opening any ttf/otf or ufo files?

@godiard explained, that one must set the mime types your activity can open and then request the object chooser to open these mime types, with more info at http://godiard.blogspot.com.ar/2013/07/sugar-programming-improovements-in.html

That question should be explained in these docs, using the info in that blog post :)

Lingering link

http://write.flossmanuals.net/make-your-own-sugar-activities/setting-up-a-development-environment/ links to http://developer.sugarlabs.org/, which is a dead link.

what-can-i-do.md has a broken link

The file what-can-i-do.md has a link to a file activity.md.html (Write a new sugar activity) which no longer exists.
It needs to be replaced with desktop-activity.md.html and web-activity.md.html.

Registering New Account On Trac Requires "Parole"

What
Registering New Account On Trac Requires "Parole"

Why
As a new user, I'm trying to register a new trac account at (https://bugs.sugarlabs.org/register) as instructed on the BugSquad/Bug Report (http://wiki.sugarlabs.org/go/BugSquad/Bug_Report) wiki page to create a query, but there's a "Parole" required that I'm unable to find even with a hint (attached screenshot). This is restricting me to make any contribution.

Screenshots

Stress the importance of testing the platform variable

From http://lists.sugarlabs.org/archive/sugar-devel/2016-May/052710.html and replies, it seems some dependencies must be changed based on XO model and on 32 or 64 bit architechture.

During GCI, Walter set up a platform variable that activities can test to determine the environment. This will become increasingly important to developers, so should be stressed (and perhaps part of Hello World.)

The XO-1.75 needs ARMv7 binaries, while older XOs used x86. Activity bundles should include .so files for each supported architecture. There is not yet a formal bundle structure for handling multi-arch, as it was designed for platform-independent code like Python, but since a bundle can have arbitrary library folders, an activity using compiled libraries must implement code to selecting the right one for the current architecture.

After a few activities have done this, perhaps a convention can be recommended in these docs for others to follow.

(Thanks to Tony Anderson and Bert Freudenberg for clarifying this issue)

Setup a development environment

Two lines below the table the link for setting up a development enviroment points to

https://developer.sugarlabs.org/dev-environment.md

Rather than point it at the corresponding html file by appending .html, we should probably just point it towards

https://github.com/sugarlabs/sugar/blob/master/docs/development-environment.md

as per our current approach.

Pull request to effect this is on its way.

Improve telepathy docs

https://www.sam.today/blog/telepathy-10-lists.html lists some issues with the way telepathy was used in activities; this suggests we can improve our docs with telepathy guidance :)

Review and improve GTK+ 3 porting workflow

https://github.com/sugarlabs/sugar-docs/blob/master/src/gtk3-porting-guide.md#how-to-port-a-sugar-activity-to-gtk-3 has a brief workflow for porting activiites.

@yashagrawal3, you may be interested in reviewing and improving this workflow.

Reference: http://meeting.sugarlabs.org/sugar-meeting/2018-05-11#i_2924905

Maintain FLOSS Manuals "Make Your Own Sugar Activities"

Lets consolidate the developer docs here, by importing and maintaining that text here