Changeset 78:b5dabe9762d1

Show
Ignore:
Timestamp:
04/12/07 17:38:04 (17 months ago)
Author:
Tarek Ziad?? <tarek@…>
Message:

rupy slides, starting up

Files:
34 added
12 modified

Legend:

Unmodified
Added
Removed

  • PyCon07/slides.txt

    r76 r78  
    2222- Creator of AFPY (french speaking PUG) 
    2323 
    24 - CTO at Emencia, for a Python e-commerce framework   
     24- CTO at Emencia, for a Python e-commerce framework 
    2525 
    2626 
    … …  
    3030- Understand the place of documentation in software projects 
    3131 
    32 - Learn a few patterns to document your project  
     32- Learn a few patterns to document your project 
    3333 
    3434- Practice them ! 
    … …  
    3838 
    3939- Each part comes with: 
    40   
     40 
    4141 - a few slides 
    4242 - exercises *you* do. 
    … …  
    5353- LUNCH - Yeeahhaa 
    5454 
    55 A few definitions  
     55A few definitions 
    5656================= 
    5757 
    5858What kind of documentation are we talking about ? 
    5959 
    60 A few definitions  
     60A few definitions 
    6161================= 
    6262 
    6363Technical documentation that helps to understand how a codebase 
    64 works and how it can be used.  
     64works and how it can be used. 
    6565 
    6666This can be: 
    … …  
    7171- a recipe 
    7272 
    73 A few definitions  
     73A few definitions 
    7474================= 
    7575 
    7676What is the use and who is the target ? 
    7777 
    78 A few definitions  
     78A few definitions 
    7979================= 
    80   
     80 
    8181- Project developers, to... 
    8282 
    … …  
    9999- Writing techniques ans tips: the seven laws 
    100100- Team writing 
    101   
     101 
    102102Mastering reSTructuredText 
    103103========================== 
    … …  
    170170=================== 
    171171 
    172 Focus on your target when you write a document (RÃŒping, 2003).  
     172Focus on your target when you write a document (RÃŒping, 2003). 
    173173 
    174174Assume their background knowledge to restrict the scope of the documentation. 
    … …  
    179179=================== 
    180180 
    181 A document is about a clear focus.  
    182  
    183 A precise title for each section and the document itself, and a summary  
     181A document is about a clear focus. 
     182 
     183A precise title for each section and the document itself, and a summary 
    184184can help. 
    185185 
    186 |important| If you cannot easily name the document or one of its section,  
     186|important| If you cannot easily name the document or one of its section, 
    187187there's a problem 
    188188 
    … …  
    197197    >>> foo = graph.calculateSquare(1, 1, 1, 1) 
    198198    >>> bar = graph.renderSquare(foo) 
    199     
    200 Better::  
     199 
     200Better:: 
    201201 
    202202    >>> from package import graph 
    … …  
    208208 
    209209A working software is more important than the best documentation in the world 
    210 (Ambler, 2002).  
     210(Ambler, 2002). 
    211211 
    212212*Quality over Quantity* is the best rule. 
    213213 
    214 |important| Spending too much time to find something in the documentation is  
     214|important| Spending too much time to find something in the documentation is 
    215215a bad sign. 
    216216 
    217 |important| Think documents like code. Always limit the size of its sections,  
     217|important| Think documents like code. Always limit the size of its sections, 
    218218examples, etc. 
    219219 
    … …  
    229229- a toc when there are more than one section 
    230230- references 
    231 - glossary  
     231- glossary 
    232232- tables and diagrams 
    233233 
    … …  
    249249|important| The best pair is made with the end-user 
    250250 
    251 |important| Each document should have a champion, though.  
     251|important| Each document should have a champion, though. 
    252252 
    253253Team writing 
    … …  
    260260    - cooking recipe 
    261261    - how to play a board or card game 
    262     - how to fish shrimps  
    263   
     262    - how to fish shrimps 
     263 
    264264 
    265265Writing a document 
    … …  
    292292   :height: 350 
    293293   :width: 250 
    294   
     294 
    295295   Developer that write documentation (=winner) 
    296296 
    … …  
    317317The code is documented with: 
    318318 
    319 - inline comments  
     319- inline comments 
    320320- functions, classes and modules docstrings 
    321321 
    … …  
    346346- The text file describes what the module does 
    347347 
    348 - example: utils.txt and utils.py  
    349  
    350 - Let's practice: exercise #5 |glasses|  
     348- example: utils.txt and utils.py 
     349 
     350- Let's practice: exercise #5 |glasses| 
    351351 
    352352 
    … …  
    360360- **CHANGELOG**: Lists of changes for each version of the package 
    361361- **INSTALL.txt**: how to install the package 
    362 - **TODO.txt**: Lists all things to do (sometimes replaced with a  
     362- **TODO.txt**: Lists all things to do (sometimes replaced with a 
    363363  link to a tracker or a website in README.txt) 
    364364 
    … …  
    464464 
    465465- There's 3 level of documentation: 
    466    
     466 
    467467  - inline comments 
    468468  - docstrings 
    469469  - separated docstrings 
    470470- Packages comes with mandatory documentation 
    471 - We can do TDD with doctests, and deal with doc. like code  
     471- We can do TDD with doctests, and deal with doc. like code 
    472472 
    473473Pause 
    … …  
    532532 
    533533- title & abstract (two sentences max) 
    534 - prerequest: level needed, other documents to read   
     534- prerequest: level needed, other documents to read 
    535535- toc (when # sections > 1) 
    536536- body 
    … …  
    551551- A recipe answer to one question, that should be its title. 
    552552 
    553 - Each question is linked to the sentences founded in tutorials.  
     553- Each question is linked to the sentences founded in tutorials. 
    554554 
    555555- A recipe is short (2 screens) 
    … …  
    561561 
    562562- How to code a RSS view ? 
    563 - How to extract the content of a web page ?  
     563- How to extract the content of a web page ? 
    564564 
    565565Recipes 
    … …  
    569569 
    570570- title & abstract (two sentences max) 
    571 - prerequest: level needed, other documents to read   
     571- prerequest: level needed, other documents to read 
    572572- toc (when # sections > 1) 
    573573- body 
    … …  
    587587- ..avoid using two terms for the same definition 
    588588- ..removes approximacies in documents: 
    589     not sure on how to explain a concept with simple words ?  
     589    not sure on how to explain a concept with simple words ? 
    590590    look in the glossary |wink| 
    591591 
    … …  
    639639- It is enjoyed by most developers 
    640640 
    641 - It increases both writing and programming skills  
     641- It increases both writing and programming skills 
    642642 
    643643The end 

  • pycommunity/pycommunity/doc/configuration.txt

    r68 r78  
    77 
    88    >>> from configuration import Configuration 
    9     >>> config = Configuration('pycommunity.conf') 
     9    >>> config = Configuration('tests/pycommunity.conf') 
    1010 
    1111packages, recipes, and tutorials folders can be read with  
    … …  
    1919    [('tuts', 'tests/svn/project/tutorials')]  
    2020    >>> config.glossary 
    21     'tests/svn/project/doc/glossary.txt' 
     21    '/etc/pycommunity/glossary.txt' 
    2222    >>> packages = config.packages.items() 
    2323    >>> packages.sort() 
    … …  
    2929    >>> templates.sort() 
    3030    >>> templates 
    31     [('css', 'templates/pycommunity.css'),  
    32      ('glossary', 'templates/glossary.pt'),  
    33      ('index', 'templates/index.pt'),  
    34      ('js', 'templates/pycommunity.js'), 
    35      ('packagedoc', 'templates/packagedoc.pt'),  
    36      ('packageindex', 'templates/packageindex.pt'),  
    37      ('packagesindex', 'templates/packagesindex.pt'),  
    38      ('packagestats', 'templates/packagestats.pt'),  
    39      ('recipe', 'templates/recipe.pt'),  
    40      ('recipelist', 'templates/recipelist.pt'),  
    41      ('tutorial', 'templates/tutorial.pt'),  
    42      ('tutoriallist', 'templates/tutoriallist.pt')]     
     31    [('css', 'tests/templates/pycommunity.css'),  
     32     ('glossary', 'tests/templates/glossary.pt'),  
     33     ('index', 'tests/templates/index.pt'),  
     34     ('js', 'tests/templates/pycommunity.js'), 
     35     ('packagedoc', 'tests/templates/packagedoc.pt'),  
     36     ('packageindex', 'tests/templates/packageindex.pt'),  
     37     ('packagesindex', 'tests/templates/packagesindex.pt'),  
     38     ('packagestats', 'tests/templates/packagestats.pt'),  
     39     ('recipe', 'tests/templates/recipe.pt'),  
     40     ('recipelist', 'tests/templates/recipelist.pt'),  
     41     ('tutorial', 'tests/templates/tutorial.pt'),  
     42     ('tutoriallist', 'tests/templates/tutoriallist.pt')]     
    4343    >>> config.media 
    44     'templates/media' 
     44    'tests/templates/media' 
    4545    >>> 'projectname' in config.options 
    4646    True 

  • pycommunity/pycommunity/doc/index.txt

    r68 r78  
    99    >>> options = {'projectname': 'PyCommunity', 
    1010    ...            'index': 'tests/svn/project/doc/README.txt'} 
    11     >>> view = IndexView('templates/index.pt', options) 
     11    >>> view = IndexView('tests/templates/index.pt', options) 
    1212    >>> print view() 
    1313    <html> 
    … …  
    2222    >>> class Conf(object): 
    2323    ...     targets = {'target1': 'tests/www'} 
    24     ...     templates = {'index': 'templates/index.pt',  
    25     ...                  'css': 'templates/pycommunity.css', 
    26     ...                  'js': 'templates/pycommunity.js'} 
    27     ...     media = 'templates/media' 
     24    ...     templates = {'index': 'tests/templates/index.pt',  
     25    ...                  'css': 'tests/templates/pycommunity.css', 
     26    ...                  'js': 'tests/templates/pycommunity.js'} 
     27    ...     media = 'tests/templates/media' 
    2828    ...     options = {'projectname': 'PyCommunity', 
    2929    ...                'index': 'tests/svn/project/doc/README.txt'} 

  • pycommunity/pycommunity/doc/package.txt

    r68 r78  
    1919    ...     targets = {'target1': 'tests/www'} 
    2020    ...     glossary = 'tests/svn/project/doc/glossary.txt' 
     21    ...     tutorials = {'recipes': 'tests/svn/project/tutorials'}     
     22    ...     recipes = {'recipes': 'tests/svn/project/recipes'}    
    2123    ...     packages = {'package1': 'tests/svn/project/src/package1', 
    2224    ...                 'package2': 'tests/svn/project/src/package2' } 
    2325    ...     options = {'projectname': 'PyCommunity', 
    2426    ...                 'packages': 'tests/svn/project/doc/packages.txt'} 
    25     ...     templates = {'packageindex': 'templates/packageindex.pt', 
    26     ...                  'packagesindex': 'templates/packagesindex.pt', 
    27     ...                  'packagestats': 'templates/packagestats.pt', 
    28     ...                  'packagedoc': 'templates/packagedoc.pt'} 
     27    ...     templates = {'packageindex': 'tests/templates/packageindex.pt', 
     28    ...                  'packagesindex': 'tests/templates/packagesindex.pt', 
     29    ...                  'packagestats': 'tests/templates/packagestats.pt', 
     30    ...                  'packagedoc': 'tests/templates/packagedoc.pt'} 
    2931    ... 
    3032 

  • pycommunity/pycommunity/doc/recipe.txt

    r68 r78  
    1212    >>> class Conf(object): 
    1313    ...     targets = {'target1': 'tests/www'} 
    14     ...     recipes = {'recipes': 'tests/svn/project/recipes'}     
    15     ...     templates = {'recipe': 'templates/recipe.pt', 
    16     ...                  'recipelist': 'templates/recipelist.pt'} 
     14    ...     tutorials = {'recipes': 'tests/svn/project/tutorials'}     
     15    ...     recipes = {'recipes': 'tests/svn/project/recipes'}    
     16    ...     templates = {'recipe': 'tests/templates/recipe.pt', 
     17    ...                  'recipelist': 'tests/templates/recipelist.pt'} 
    1718    ...     glossary = 'tests/svn/project/doc/glossary.txt' 
    1819    ... 

  • pycommunity/pycommunity/doc/resttask.txt

    r68 r78  
    99 
    1010    >>> from resttask import TaskView 
    11     >>> view = TaskView('templates/recipe.pt',  
     11    >>> view = TaskView('tests/templates/recipe.pt',  
    1212    ...                 'tests/svn/project/recipes/glossary_recipe.txt', 
    13     ...                 'tests/svn/project/doc/glossary.txt') 
     13    ...                 'tests/svn/project/doc/glossary.txt', 
     14    ...                 ['tests/svn/project/doc/tutorials'], []) 
    1415    ... 
    1516    >>> title, content = view() 

  • pycommunity/pycommunity/doc/sitebuilder.txt

    r68 r78  
    77 
    88    >>> from sitebuilder import buildSite 
    9     >>> buildSite() 
     9    >>> buildSite('tests/pycommunity.conf') 
    1010     
    1111Checking the structure:: 

  • pycommunity/pycommunity/doc/tutorial.txt

    r68 r78  
    1212    >>> class Conf(object): 
    1313    ...     targets = {'tutorial1': 'tests/www'} 
     14    ...     recipes = {} 
    1415    ...     tutorials = {'tutorials': 'tests/svn/project/tutorials'} 
    15     ...     templates = {'tutorial': 'templates/tutorial.pt', 
    16     ...                  'tutoriallist': 'templates/tutoriallist.pt'} 
     16    ...     templates = {'tutorial': 'tests/templates/tutorial.pt', 
     17    ...                  'tutoriallist': 'tests/templates/tutoriallist.pt'} 
    1718    ...     glossary = 'tests/svn/project/doc/glossary.txt' 
    1819    ... 

  • pycommunity/pycommunity/package.py

    r68 r78  
    158158        self._glossary_file = configuration.glossary 
    159159        self._options = configuration.options 
     160        self._tutorials = configuration.tutorials 
     161        self._recipes = configuration.recipes 
    160162 
    161163        for target in targets: 
    … …  
    199201        template = self._rest_template 
    200202        glossary = self._glossary_file 
     203        tutorials = self._tutorials 
     204        recipes = self._recipes 
    201205 
    202206        for file_ in files: 
    203             view = TaskView(template, file_, glossary) 
     207            view = TaskView(template, file_, glossary, tutorials, recipes) 
    204208            filename = os.path.join(folder, self._getHTMLName(file_)) 
    205209            self._writeFile(filename, view()[1]) 

  • pycommunity/pycommunity/resttask.py

    r68 r78  
    3131class TaskView(object): 
    3232    """generates a base view""" 
    33     def __init__(self, templatefile, restfile, glossaryfile): 
     33    def __init__(self, templatefile, restfile, glossaryfile, tutorial_folders, 
     34                 recipe_folders): 
    3435        title, content = rest2Web(restfile) 
    35         content = linkChecker(content, glossaryfile) 
     36        content = linkChecker(content, glossaryfile, tutorial_folders, 
     37                              recipe_folders) 
    3638        self.title = title 
    3739        self._template = Template(open(templatefile).read(), 
    … …  
    98100                    # generating the view 
    99101                    view = TaskView(self._getTemplateFile(configuration), 
    100                                     restfile, configuration.glossary) 
     102                                    restfile, configuration.glossary, 
     103                                    configuration.tutorials, 
     104                                    configuration.recipes) 
    101105                    title, result = view() 
    102106                    titles.append(title) 

  • pycommunity/pycommunity/utils.py

    r68 r78  
    8989        return None 
    9090 
    91 def _grabContent(type, name): 
     91def _grabContent(type, name, tutorial_folders, recipe_folders): 
    9292    """gets a recipe or a turotial content""" 
    9393    return """<b>Soon</b>""" 
    9494 
    95 def linkChecker(content, glossaryfile): 
     95def linkChecker(content, glossaryfile, tutorial_folders, recipe_folders): 
    9696    """changes links on the fly""" 
    9797    glossary = GlossaryReader(glossaryfile) 
    … …  
    112112        if 'recipe' in match.group(): 
    113113            link = '../recipes/%s.html' % name 
    114             content = _grabContent('recipes', name) 
     114            content = _grabContent('recipes', name, tutorial_folders, 
     115                                   recipe_folders) 
    115116        else: 
    116117            link = '../tutorials/%s.html' % name 
    117             content = _grabContent('tutorials', name) 
     118            content = _grabContent('tutorials', name, tutorial_folders, 
     119                                   recipe_folders) 
    118120 
    119121        url = re_docs[1] 

  • pycommunity/setup.py

    r77 r78  
    6767      maintainer_email="tarek@ziade.org", 
    6868      url = url, 
    69       download_url = '%s/PyCommunity-0.1a-py2.5.egg' % url, 
     69      #download_url = '%s/PyCommunity-0.1a-py2.5.egg' % url, 
    7070      license = "http://www.gnu.org/copyleft/gpl.html", 
    7171      platforms = ["any"],