[cairo-commit] pycairo/doc c-api.rst, NONE, 1.1 conf.py, NONE, 1.1 faq.rst, NONE, 1.1 index.rst, NONE, 1.1 Makefile.am, 1.2, 1.3 overview.rst, NONE, 1.1 README, NONE, 1.1

[Steve Chaplin]

Committed by: stevech1097

Update of /cvs/cairo/pycairo/doc
In directory kemper:/tmp/cvs-serv27414/doc

Added Files:
	c-api.rst conf.py faq.rst index.rst Makefile.am overview.rst 
	README 
Log Message:
'SC'

--- NEW FILE: c-api.rst ---
***********************
C-API (unfinished docs)
***********************
--- NEW FILE: conf.py ---
# -*- coding: utf-8 -*-
#
# pycairo documentation build configuration file, created by
# sphinx-quickstart on Tue Nov 25 23:21:00 2008.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# The contents of this file are pickled, so don't put values in the namespace
# that aren't pickleable (module imports are okay, they're removed automatically).
#
# All configuration values have a default; values that are commented out
# serve to show the default.

import sys, os

# If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
#sys.path.append(os.path.abspath('.'))

# General configuration
# ---------------------

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']

# The suffix of source filenames.
source_suffix = '.rst'

# The encoding of source files.
#source_encoding = 'utf-8'

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = u'pycairo'
copyright = u'2008, Steve Chaplin'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.8'
# The full version, including alpha/beta/rc tags.
release = '1.8.0a'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'

# List of documents that shouldn't be included in the build.
#unused_docs = []

# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = ['.build']

# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'


# Options for HTML output
# -----------------------

# The style sheet to use for HTML and HTML Help pages. A file of that name
# must exist either in Sphinx' static/ path, or in one of the custom paths
# given in html_static_path.
html_style = 'default.css'

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
#html_title = None

# A shorter title for the navigation bar.  Default is the same as html_title.
#html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None

# The name of an image file (within the static path) to use as favicon of the
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['.static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}

# If false, no module index is generated.
#html_use_modindex = True

# If false, no index is generated.
#html_use_index = True

# If true, the index is split into individual pages for each letter.
#html_split_index = False

# If true, the reST sources are included in the HTML build as _sources/<name>.
#html_copy_source = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''

# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''

# Output file base name for HTML help builder.
htmlhelp_basename = 'pycairodoc'


# Options for LaTeX output
# ------------------------

# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'

# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
latex_documents = [
  ('index', 'pycairo.tex', ur'pycairo Documentation',
   ur'Steve Chaplin', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False

# Additional stuff for the LaTeX preamble.
#latex_preamble = ''

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_use_modindex = True

--- NEW FILE: faq.rst ---
***
FAQ
***

Pycairo FAQ - Frequently Asked Questions
========================================

Q: Can I subclass pycairo classes?

A: Cairo, the C library, is not an object oriented library, so a Python
binding can never be a truly object oriented interface to cairo.  One way to
write the Python bindings for cairo would be as a single long list of module
functions - this would be the most accurate representation of the underlying C
library. Pycairo (and most other cairo language bindings?) instead chose to
implement the bindings using Context, Surface, Pattern, etc classes.  An
advantage is that the classes organise cairo into groups of similar functions.
A disadvantage is that creates an illusion that cairo is object oriented
library, and people are then tempted to create subclasses to override cairo
methods. When in fact there are no methods to override, just cairo functions
which can't be overridden.

The cairo documentation Appendix A "Creating a language binding for cairo"
section "Memory Management" describes why deriving from a Surface creates
problems and is best avoided.

cairo.Context can be subclassed.
All other pycairo subclasses cannot be subclassed.


Q: How do I use pycairo with numpy?

A: See test/isurface_create_for_data2.py


Q: How do I use pycairo with pygame?

A: See test/pygame-test1.py
       test/pygame-test2.py

--- NEW FILE: index.rst ---
Pycairo Documentation
=====================

.. toctree::
   :maxdepth: 1

   overview
   reference/index
   faq
   c-api


Indices and tables
==================

* :ref:`genindex`
* :ref:`search`



--- NEW FILE: overview.rst ---
********
Overview
********

Pycairo is a Python binding for the cairo graphics library.

The Pycairo bindings are designed to match the cairo C API as closely as
possible, and to deviate only in cases which are clearly better implemented in
a more 'Pythonic' way.

Features of the Pycairo bindings:

* Provides an object oriented interface to cairo, using Python 2.2 new style classes.
* Pycairo_Check_Status() is called to check the status of cairo operations, and raise exceptions as appropriate.
* Provides a C API that can be used by other Python extensions.

The C cairo functions cairo_reference(), cairo_destroy(),
cairo_surface_reference(), cairo_surface_destroy() (and their equivalents for
surfaces and patterns) are not made public by the pycairo bindings. This is
because pycairo handles cairo object construction and destruction.

To use the pycairo library::

  import cairo

See :ref:`Reference <reference_index>` for further details.

For examples of pycairo code see the 'examples' directory that comes with the
pycairo distribution.

--- NEW FILE: README ---
Pycairo Documentation README
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This directory contains the reStructuredText (reST) sources to the Pycairo
documentation.

Options for accessing pycairo documentation:
1. Read the documentation online at http://cairographics.org
   - is not available yet, but it should be there eventually.

2. Download the latest 'pycairo-x.x.x-docs-html.tar.gz' prebuilt documents
from http://www.cairographics.org/releases/. Uncompress the docs and point
your browser at the index.html file.

3. Build the documentation yourself - the hardest option, see details below.


Building the docs
=================
You need to install Python 2.4 or higher; the toolset used to build the docs are
written in Python.  The toolset used to build the documentation is called
*Sphinx*, it is not included in this tree, but maintained separately in the
Python Subversion repository.  Also needed are Jinja, a templating engine
(included in Sphinx as a Subversion external), and optionally Pygments, a code
highlighter.


Using make
----------
   make html

Available make targets are:

 * "html", which builds standalone HTML files for offline viewing.

 * "htmlhelp", which builds HTML files and a HTML Help project file usable to
   convert them into a single Compiled HTML (.chm) file -- these are popular
   under Microsoft Windows, but very handy on every platform.

   To create the CHM file, you need to run the Microsoft HTML Help Workshop
   over the generated project (.hhp) file.

 * "latex", which builds LaTeX source files that can be run with "pdflatex"
   to produce PDF documents.

 * "text", which builds a plain text file for each source file.

 * "linkcheck", which checks all external references to see whether they are
   broken, redirected or malformed, and outputs this information to stdout
   as well as a plain-text (.txt) file.

 * "changes", which builds an overview over all versionadded/versionchanged/
   deprecated items in the current version. This is meant as a help for the
   writer of the "What's New" document.

 * "pydoc-topics", which builds a Python module containing a dictionary
   with plain text documentation for the labels defined in
   `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic
   and keyword help.

A "make update" updates the Subversion checkouts in `tools/`.


Without make
------------

You'll need to checkout the Sphinx package to the `tools/` directory::

   svn co http://svn.python.org/projects/doctools/trunk/sphinx tools/sphinx

Then, you need to install Docutils 0.4 (the SVN snapshot won't work), either
by checking it out via ::

   svn co http://svn.python.org/projects/external/docutils-0.4/docutils tools/docutils

or by installing it from http://docutils.sf.net/.

You can optionally also install Pygments, either as a checkout via ::

   svn co http://svn.python.org/projects/external/Pygments-0.9/pygments tools/pygments

or from PyPI at http://pypi.python.org/pypi/Pygments.


Then, make an output directory, e.g. under `build/`, and run ::

   python tools/sphinx-build.py -b<builder> . build/<outputdirectory>

where `<builder>` is one of html, web or htmlhelp (for explanations see the make
targets above).