jewelfox: A portrait of a foxgryphon with a beak, black fur, magenta hair, fox ears, and a neckband with a large jewel on it. (Default)
[personal profile] jewelfox
Here's a summary of what I've learned about how to write GNOME developer documentation. I'm going to be referencing this a lot during the Outreach Program for Women internship, so I wanted to have it all in one place, preferably public so that others can read or critique it.

Update: This page contains a much better reference, and I am working on adding any unique content here to it and the rest of the GNOME wiki.

Many thanks to Tiffany Antopolski, aka mimico on the IRC, as well as the others on IRC for helping!

  1. Git-ting started

  2. How to write code samples (as listed here)

  3. Taking screenshots and showing your work

  4. Resources and links


Git-ting started

Git is the version control system used by the GNOME project. It lets you backtrack to any point in your work, as though you had a list of game save files for it, and also helps manage things for when multiple people are working on it.

First, you need to have git installed. Follow the instructions for installing files on your Linux distro. Normally this will involve searching whatever application you use to install software for "git", or typing something like
su -c "yum install git"

or

sudo apt-get install git
in the terminal. If you aren't using GNOME 3.4 or later, you'll also need to set up a JHBuild environment (instructions at the link).

Once you have git installed, create a folder to put your local copies of the GNOME documentation files, go there in the terminal, and type
git init
After that, type
git clone git://git.gnome.org/gnome-devel-docs
to get your local copy. You only need to do these two parts once.

Finally, type
git add .
to tell git to start tracking everything that you've just copied. You'll type this again after every change that you've made, and will then use git commit to add your changes. Git for the lazy has detailed (but not too detailed) instructions for how to add and commit your changes, which is like creating a new video game save file with the progress you've made. You'll ideally want to write a commit log, or description, for each one.

By default you'll be thrown into some kind of complex, console-mode text editor like vim to write these logs, which can be confusing since it doesn't tell you the commands. If you'd like to use gedit (the default text editor on most Linux distros that use GNOME) instead, type the following command before you start writing commits:
git config --global core.editor "gedit -w -s"
You only have to type it once, and it'll work from then on for that computer.

To send your changes in to the GNOME project, you'll want to create a .patch file which contains the changes you've made, then open a bug report on the GNOME Bugzilla and enclose the .patch file as an attachment. To create a .patch file after you've already made a commit, type
git format-patch HEAD^
Use another ^ for every commit you've made so far, that you'd like to have put in the patch. You can use
git log
if you need a reminder of what you've been working on. Then file the bug on bugzilla.gnome.org.

When you get back to work another day, and would like to have the latest copy of everyone's work, use this command:
git pull --rebase
If you haven't committed the changes you're working on yet, use these three commands instead:
git stash
git pull --rebase
git stash pop
They "stash" the changes you've made so far, then "pop" them back out after you've rebased the code.

Git can be fickle, so don't hesitate to ask for help on the GNOME IRC on #docs.



How to write code samples

First, you need to have git set up and have pulled down the latest files. If you're using gedit -- which is the default text editor on Fedora, Ubuntu, and many other Linux distros and is often just called "text editor" -- you also need to have this gedit plugin installed. (Click the "Raw" tab for each plugin file to get to the file itself, then use "Save Page As ... " to put it in the gedit plugins directory. There are instructions for how to create a plugins directory at the link.)

In your project directory, create the code sample itself in gnome-devel-docs/platform-demos/C/samples. Then to create the corresponding page in the developer docs (without having to cut and paste code!), go back to gnome-devel-docs/platform-demos/C (by typing "cd .. ") and type
cp widget.LANGUAGE.page ENTRY.LANGUAGE.page
Replace LANGUAGE with the language you're using (JavaScript is just "js" here) and replace ENTRY with the specific widget you're writing a code sample for. Then type
gedit ENTRY.LANGUAGE.page
You can replace "gedit" with the name of another text editor, if you like. Either way, next change the following:
  1. ID (line 4)

  2. Xref section link (line 6)

  3. Date

  4. Change page status from "stub" to "draft"

  5. Your name, email address, and year

  6. The <desc>

  7. The <title>

  8. The more detailed description

  9. The href="samples/filename" part (so it sees which sample to pull for the page)

  10. The links at the bottom (to the widgets used in your example)
Now you're all set! Just follow the instructions on live.gnome.org to create a .patch file and submit it to the GNOME Bugzilla.



Taking screenshots and showing your work

First, you should be using the latest version of GNOME, since its appearance keeps getting updated. The 3.4 version, for instance, removed the resize grip in the bottom-right corner. You also need to turn off any custom themes, and accessibility features like Large Text that would change the screenshot's appearance.

To take a screenshot of just the application window, press the PrintScreen button on your keyboard (often labeled "PrtScn" or "prt sc" or something), and check the box that says "Capture current window." Alternately, hold down Alt while pressing PrintScreen, while the focus is on the window you want to take a screenshot of.

If you'd like to show people on IRC or the web what you're working on, a quick way is to type
fpaste FILENAME

or

pastebinit FILENAME
fpaste works if you're on Fedora, while pastebinit works for Ubuntu or Mint. You'll need to have the fpaste or pastebinit programs installed first.



Resources and links

Git
GNOME
  • Beginner Tutorial tasts -- This is a list of everything that needs to be done for the GNOME developer beginner courses. It has a sort of whiteboard for keeping track of which parts have been done so far.
GTK+
  • GtkApplication -- Detailed info on the base class for any application built using the GTK+ toolset.

  • GtkApplicationWindow -- Info on the class used for giving your application a window. It differs from the old GtkWindow in that it has support for things like the application menu built in.
JavaScript

Thank you

Date: 2012-05-22 09:35 pm (UTC)
From: [identity profile] planningadinner.blogspot.com
Hi, I am another OPW intern - I will be doing the developers documentation in Python. Thank you very much for writing this down, it's so useful!

About us

~ Fox | Gem | Rei ~

We tell stories, paint minis, collect identity words, and share them all with our readers. If something we write helps you, let us know.

~ She / her ~

Tags

Style Credit

Page generated Jun. 24th, 2017 08:47 am
Powered by Dreamwidth Studios