pygccxml-commit

[<rom...@us...>]

Revision: 1631
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1631&view=rev
Author:   roman_yakovenko
Date:     2009-01-28 14:42:41 +0000 (Wed, 28 Jan 2009)

Log Message:
-----------
converting pydsc documentation to sphinx

Modified Paths:
--------------
    pydsc_dev/docs/definition.rest
    pydsc_dev/docs/pydsc.rest
    pydsc_dev/pydsc.py

Added Paths:
-----------
    pydsc_dev/docs/api.rest

Added: pydsc_dev/docs/api.rest
===================================================================
--- pydsc_dev/docs/api.rest	                        (rev 0)
+++ pydsc_dev/docs/api.rest	2009-01-28 14:42:41 UTC (rev 1631)
@@ -0,0 +1,7 @@
+=========
+pydsc API
+=========
+
+.. automodule:: pydsc
+    :members:
+

Modified: pydsc_dev/docs/definition.rest
===================================================================
--- pydsc_dev/docs/definition.rest	2009-01-28 11:49:43 UTC (rev 1630)
+++ pydsc_dev/docs/definition.rest	2009-01-28 14:42:41 UTC (rev 1631)
@@ -1 +1 @@
-`pydsc`_ - Python documentation string spell checker
\ No newline at end of file
+:mod:`pydsc` - PYthon Documentation string Spell Checker

Modified: pydsc_dev/docs/pydsc.rest
===================================================================
--- pydsc_dev/docs/pydsc.rest	2009-01-28 11:49:43 UTC (rev 1630)
+++ pydsc_dev/docs/pydsc.rest	2009-01-28 14:42:41 UTC (rev 1631)
@@ -4,6 +4,11 @@
 
 .. contents:: Table of contents
 
+.. toctree::
+   :maxdepth: 2
+
+   API <api>
+
 .. meta::
    :description: Python documentation string spell checker
    :keywords: Python, docstring, documentation, spell, check
@@ -19,52 +24,57 @@
 What it is useful for?
 ----------------------
 
-Well, this project was born to solve real problem - I made a lot of mistakes,
-when I write source code documentation for my projects. I needed some way to
-check all the documentation strings.  My goal was simplicity + easy customization.
-I achieved it. Here is example of usage of pydsc:
+The `pydsc`_ module checks documentation strings and comments for spelling errors.
 
+Usage example
+-------------
+
+It is very easy to start using :mod:`pydsc` module - just import it:
+
 .. code-block:: python
 
   import pydsc
-  #every module that will be imported after pydsc will be checked
-  #all errors will be printed to stdout
-  import readline
 
---------------
-Spell checking
---------------
+and every module, that will be imported after it, will be checked. The errors
+will be printed to stdout.
 
-I did not reinvent the wheel. I use external spell checking engine. I checked
-around and found few spell check engines available from Python. I decided to use
-`PyEnchant`_. It is cross platform, has clean interface and responsive author.
+For example:
 
--------------
-Usage example
--------------
-
-Basic usage is really simple, but sometimes there is a need to:
-  * skip\\exclude some words from checking
-  * redefine error messages destination, for example to print to some file
-  * exclude(include) files from(to) spell checking process by file location
-    ( very useful option in multi-project environment )
-
-"More complex" example:
-
 .. code-block:: python
 
   import pydsc
-  #check for spell errors only in files under "/home/roman/pygccxml" directory
-  pydsc.include( "/home/roman/pygccxml" )
-  pydsc.ignore( [ 'normcase', 'normpath' ] )
   import readline
 
+:mod:`pydsc` contains few functions, which helps you to configure the spell checker:
+  * to define your own "ignore" dictionary
+  * to define the error messages destination (file, stdout)
+  * to define set of files, which should be included or excluded
+
+For more information see :mod:`pydsc` module.
+
+------------
+Spell engine
+------------
+
+:mod:`pydsc` modules uses `PyEnchant`_ one.
+
+The `PyEnchant`_ package provides interface for different spell engines:
+    * ispell
+    * aspell
+    * OpenOffice
+
 --------
 Download
 --------
 
 http://sourceforge.net/project/showfiles.php?group_id=118209
 
+------------
+Installation
+------------
 
+python setup.py install
+
+
 .. _`pydsc`: ./pydsc.html
 .. _`PyEnchant`: http://pyenchant.sourceforge.net/

Modified: pydsc_dev/pydsc.py
===================================================================
--- pydsc_dev/pydsc.py	2009-01-28 11:49:43 UTC (rev 1630)
+++ pydsc_dev/pydsc.py	2009-01-28 14:42:41 UTC (rev 1631)
@@ -4,73 +4,16 @@
 # http://www.boost.org/LICENSE_1_0.txt)
 
 """
-Python Documentation Spell Checker.
+The pydsc module checks documentation strings and comments for spelling errors.
 
-The pydsc module contains functionality needed to check documentation strings
-and comments for spelling errors, within Python code. The pydsc module depends
-on PyEnchant spell checker. PyEnchant provides interface for different spell
-engines:
-    * ispell
-    * aspell
-    * OpenOffice
-
-The use of the pydsc module is very simple - just import pydsc and all modules
-that will be imported after it will be checked. By default all spelling errors
-will be printed to sys.stdout. The pydsc checker could be customized in many
-different ways:
-    * you can define set of files/directories that should be included/excluded
-      from check process
-    * you can redefine error messages destination
-    * you can redefine and/or re-configurate spell checker
-
-Install:
-python setup.py install
-
 Usage example:
 
-import pydsc
-import readline #errors will be printed to standart output
+.. code-block:: python
 
-more complex example ( taken from pygccxml project ):
-
-import pydsc
-#check only pygccxml package
-pydsc.include( r'D:\pygccxml_sources\sources\pygccxml_dev' )
-pydsc.ignore( [ 'Yakovenko'
-    , 'Bierbaum'
-    , 'org'
-    , 'http'
-    , 'bool'
-    , 'str'
-    , 'www'
-    , 'param'
-    , 'txt'
-    , 'decl'
-    , 'decls'
-    , 'namespace'
-    , 'namespaces'
-    , 'enum'
-    , 'const'
-    , 'GCC'
-    , 'xcc'
-    , 'TODO'
-    , 'typedef'
-    , 'os'
-    , 'normcase'
-    , 'normpath'
-    , 'scopedef'
-    , 'ira'#part of Matthias mail address
-    , 'uka'#part of Matthias mail address
-    , 'de'#part of Matthias mail address
-    , 'dat'#file extension of directory cache
-    , 'config'#parameter description
-    , 'gccxml'#parameter description
-    , 'Py++'
-    , 'pygccxml'
-    , 'calldef'
-    , 'XXX'
-    , 'wstring'
-    , 'py' ] )
+   import pydsc
+   pydsc.include( r'D:\pygccxml_dev\pygccxml' ) #check only pygccxml package
+   pydsc.exclude( r'C:\Python' ) #don't check standard library
+   pydsc.ignore([ 'Yakovenko', 'www', 'org', 'py' ])
 """
 
 __version__ = '0.2' #current version
@@ -85,18 +28,15 @@
 import __builtin__
 from enchant import checker
 
-
-#TODO: source code encoding
-# -*- coding: encoding -*-
-# -*- coding: iso-8859-15 -*-
-
 def normalize_path( some_path ):
     """return os.path.normcase( os.path.normpath( some_path ) )"""
     return os.path.normcase( os.path.normpath( some_path ) )
 
 class filter_by_path_t:
-    """The instance of this class will help user to define filter, that will
-    exclude modules from being checked"""
+    """
+    Utility class, should not be used directly.
+    """
+
     class FILTER_TYPE:
         """defines few filter constants"""
         INCLUDE = 'include'
@@ -142,13 +82,11 @@
 
 class checker_t( object ):
     """
-    applies spell check process on every imported module
+    Applies spell check process on every imported module.
 
-    This is the main class of this module. This class applies spell check
-    process on every imported module. Every documentation string within the
-    module will be checked. Some comments will be checked too. You should read
-    inspect module documentation, in order to find out which comments will be
-    checked.
+    Every documentation string within the imported modules will be checked.
+    Some comments will be checked too. The :mod:`inspect` module is used to
+    extract documentation strings and comments
     """
 
     def __init__( self
@@ -280,28 +218,29 @@
             self.__checked.add( id(member) )
 
 """documentation spell checker instance"""
-doc_checker = checker_t( checker.SpellChecker( "en_US" ) )
+doc_checker = None
+if 'sphinx' not in os.environ['PYDSC']:
+    doc_checker = checker_t( checker.SpellChecker( "en_US" ) )
 
 def exclude( what ):
     """
-    Convenience function. It will exclude all modules, that their source file or
-    parent directory belongs to "what".
+    excludes all modules, from the check process, that are lying in *what* directory(ies)
 
-    what - list of paths, could contain file and directory names
+    *what* - a path or list of paths, could be or contain file and/or directory names
     """
     doc_checker.filter = filter_by_path_t( what, filter_by_path_t.FILTER_TYPE.EXCLUDE )
 
 def include( what ):
     """
-    Convenience function. It will include only modules, that their source file
-    or parent directory belongs to "what".
+    includes all modules, to the check process, that are lying in *what* directory(ies)
 
-    what - list of paths, could contain file and directory names
+    *what* - a path or list of paths, could be or contain file and/or directory names
     """
     doc_checker.filter = filter_by_path_t( what, filter_by_path_t.FILTER_TYPE.INCLUDE )
 
 def ignore( what, case_sensitive=False ):
-    """Adds word or list of words to the ignore list.
+    """
+    adds *what*, word or list of words, to the ignore list.
 
     what - word(string) or list of words(strings) to be ignored.
     """


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.