Add documentation.

1 files changed, 53 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..a0d01e0
--- /dev/null
+++ b/README
@@ -0,0 +1,53 @@
+This software produces a class relationship UML-like graph from a given set of
+Python source files. It uses graphviz Python bindings and the dot layout for
+graph generation and epydoc internals for source introspection.
+
+This software will, by default (without any specific code documentation) display
+the classes hierarchy. Using the --all-methods or --all-properties options, il
+will also display the methods and/or properties of each class under the class
+name. Without these options, methods and properties can also be displayed
+individually by adding @doc to the option/method docstring. Properties can also
+be displayed by specifying the property type (this cannot be automatically
+guessed because of the dynamic typing aspect of python) in the property
+docstring, using the "@type: propertytype" syntax. Last, use relationships
+between classes can also be specified in the class docstring using the
+"@uses: otherclass" syntax.
+
+Note that symmetric options for --all-methods/properties and @doc exist :
+specifying @nodoc in the docstring will remove the method/property from the
+produced display when using the --all-methods/properties options, and
+--no-method/--no-property options will remove all the methods and properties
+from display. Last, note that the software behavior is not documented when
+symmetric options are used (that is, using --all-methods together with
+--no-methods may do weird things, which is arguably understandable).
+
+The example.py distributed with this software shows how to correctly use the
+docstrings. The example.png file shows the corresponding output, which was
+produced by running
+    $ python umlpy.py --png -o example.png -p "example."
+
+The most basic usage of this software is to simply pass it the name of the
+modules you want to graph (you obviously need to be in the right directory) :
+    $ python umlpy.py mysource.py mymodule
+The result will be written to the uml.pdf file by default. The output filename
+can be modified using the -o (or --output) option. The output format is set
+using one of the --png, --pdf and --jpg options.
+
+Class names can be shortened using a common prefix specified with the -p option.
+For instance, if you are working on a module called verylongmodulename, you can
+pas -p verylongmodulename. to the software, so that
+verylonmodulename.submodule.ClassName
+will be displayed (and internally seen as) as submodule.ClassName.
+
+Specific classes matching regexps can also be excluded, re-included or display
+forced. That is, if you want to excludes all classes whose name matches
+"^events.", you just need to pass -f "^events\\." option to the software. If you
+want to excludes these classes but those matching "^events.EventSerializer",
+pass -i "^events\\.EventSerializer" option. If you want to force the display
+(that is, display classes that would not be displayed otherwise, for instance if
+they have no relationship with any other displayed class) of classes matching
+"^parser.", use -f "^parser\\." option.
+
+This software is still very young and feature requests or bug reports are more
+than welcome at guillaume [at] segu [dot] in. Please clearly specify in the
+email subject that you're mailing about this software.