root / PyCon07 / exercises.txt

Exercise 1
==========

Duration
::::::::

10 mn

Goals
:::::

- Mastering the basic reST syntax:

    - structuration
    
    - examples

    - font effects

- Using `docutils`  

Outline
:::::::

Let's create a first reST file. The goal is to create a file that renders
like the provided HTML example: **Monty Python**. You can use `docutils` 
to render your file and compare it.

Prerequisites
:::::::::::::

- `docutils` is installed

Exercise 2
==========

Duration
::::::::

10 mn

Goals
:::::

- mastering advanced reST syntax (the useful things)

Outline
:::::::

Take back the rest file from exercise 1, and add:

- a table of content
- an external link
- a figure (image+legend)
- an anchor
- a footnote 
- metadata in fields (author, contact)

So it looks like the provided example **Monty Python 2**

Prerequisites
:::::::::::::

- Grab the picture here: http://upload.wikimedia.org/wikipedia/en/thumb/c/cb/Flyingcircus_2.jpg/300px-Flyingcircus_2.jpg or on the provided example.

Exercise 3
==========

Duration
::::::::

10 mn


Goals
:::::

- mastering useful technical writing techniques

Outline
:::::::

Take the provided file, and do:

- a structuration (toc, summary, references)
- a google-ification of all titles

Prerequisites
:::::::::::::

- Grab the file here: burgundy_before.txt

Exercise 4 (experimental)
=========================

Duration
::::::::

20 mn


Goals
:::::

- practicing pair-documenting

Outline
:::::::

This exercise is done in 3 parts.

Make binomials with two roles, a technician and a writer.

Part 1
------

The technician writes a small text about a topic she knows really well
for about 5 mn. She doesn't bather at all about the style and uses
his technical domain vocabulary to be the more accurate she can.

Part 2
------

The writer then takes the lead and try to enhance the document. She 
interviews the technician while she works, and creates a glossary if needed.

Part 3
------

Binomials moves around the room, to another desk, and review together
another binomial text, without their help.

Prerequisites
:::::::::::::

- binomials ;) 

Exercise 5
==========

Goals
:::::

- Learn how to document a Python module

Outline
:::::::

Take the provided package, and document the modules that seem 
important to you. Put all text files in a `doc` folder.

Prerequisites
:::::::::::::

- Get the package tarball in `material` 
- Get the text file that explains how pycommunity works, and
  the one that lists its main modules.

Exercise 6
==========

Goals
:::::

- Learn how to document a Python package

Outline
:::::::

Take the provided package, and create the mandatory files. You 
may use Cheesecake to test it.

Prerequisites
:::::::::::::

- Get the package tarball in `material` 

Exercise 7
==========

Goals
:::::

- Learn how to doctest

Outline
:::::::

Take the previous package, and add unit tests for all class. Decide
what goes into the doctest and what goes into the unittest.

Prerequisites
:::::::::::::

- Get the test framework here: xxx (test_docs.py and test_module.py)

Exercise 8
==========

Goals
:::::

- Learn how to design through doctest

Outline
:::::::

Create a Python package that implements a class. This class
takes a text file name when it's instantiated, and provide a few  
methods to:

- get the len of the text

- print the text

- print the first line and the last line

- returns the position of a given word or sentence

This class is created through its doctest, using TDD principles
(the test is written before the code). Pay attention to the naming
work and API design.

Prerequisites
:::::::::::::

- You know how to code in Python

- Grab `test_docs.py` to run your tests

Exercise 9
==========

Goals
:::::

- Learn how to write a tutorial

Outline
:::::::

Write a tutorial for the given feature, don't forget to apply the seven
rules. Do not insert any example of code, instead, just insert a simple
sentence that explains what the example does. 

Use this template:

- title
- abstract (two sentences max)
- toc (when # sections > 1)
- body

Feature::

    To simplify the exercise, our bundle is the Python Library.

    Let's write a tutorial on how to extract a list of web pages and create
    a local copy. The list of pages are configured in a **ini** file, and
    there's a list of words that we want to make more visible, with a **bold**
    tag.

    The modules* used are:
        - *ConfigParser* to read the conf file
        - *urllib2*, to grab the web pages
        - *re*, to bold some words.

    * we do not make a difference here between a module and a package

Prerequisites
:::::::::::::

N/A

Exercise 10
===========

Goals
:::::

- Learn how to write a few recipes

Outline
:::::::

Write the recipe "How to use ConfigParser"

Prerequisites
:::::::::::::

- exercise 9

Exercise 11
===========

Goals
:::::

- Generate documentation using PyCommunity.

Outline
:::::::

Take the provided PyCommunity tarball (documented), and generate the 
documentation over the tests, by calling `pycommunity`. Change the tutorials, 
recipes, etc, to see how the generated website is changed.

Prerequisites
:::::::::::::

N/A