Skip to content

Commit

Permalink
[doc] reorganising the doc adding the skeleton for the main sections
Browse files Browse the repository at this point in the history
  • Loading branch information
dpinte committed Apr 2, 2012
1 parent 19ef369 commit b18256b
Show file tree
Hide file tree
Showing 9 changed files with 92 additions and 27 deletions.
2 changes: 1 addition & 1 deletion docs/source/api.rst
Expand Up @@ -34,7 +34,7 @@ quantlib
:members:

quantlib.indexes
--------------------
----------------

.. currentmodule:: quantlib.index

Expand Down
13 changes: 1 addition & 12 deletions docs/source/cython_wrapper.rst
@@ -1,4 +1,3 @@
========================================
How to wrap QuantLib classes with cython
========================================

Expand Down Expand Up @@ -26,7 +25,7 @@ After wrapping the C++ class, this class is now available in python:


The Interface Code
==================
------------------

To expose QL class ''foo'', you need to create three files. For the sake of
standardization, they should be named as follows:
Expand Down Expand Up @@ -149,13 +148,3 @@ constructor of the shared_ptr to get a local copy of it, stack allocated (there
is no need to use new)


Issues
======


Common cython compiler error messages
-------------------------------------

We have gathered in this section information about common errors in the
interfacing code, how to identify them and what to do to fix them.

48 changes: 48 additions & 0 deletions docs/source/getting_started.rst
@@ -0,0 +1,48 @@
Getting started
===============

PyQL - an overview
------------------

Why building a new set of QuantLib wrappers for Python ?

The SWIG wrappers provide a very good coverage of the library but have
a number of pain points:

* few Pythonic optimisation in the syntax: the code a user must writeon the Python side looks like the C++ version
* no docstring or function signature available on the Python side
* complex debugging and complex customization of the wrappers
* monolithic build process
* complete loss of the C++ code organisation with a flat namespace in Python
* SWIG typemaps development is not that fun

For those reasons and to have the ability to expose some of the
QuantLib internals that could be very useful on the Python side, we
chosed another road. PyQL is build on top of Cython and creates a thin
Pythonic layer on top of QuantLib. It allows a tight control on the
wrapping and provides higher level Python integration.

Features:
+++++++++

* Integration with standard datatypes (like datetime objects) and numpy arrays
* Simplifed API on the Python side (e.g. usage of Handles completely hidden from the user)
* Support full docstring and expose detailed function signatures to Python
* Code organised in subpackages to provide a decent namespace, very close to the C++ code organisation
* Easy extendibility thanks to Cython and shorter build time when adding new functionnalities
* Sphinx documentation


Building and installing PyQL
----------------------------

PyQL must be installed on a system that has access to a build of QuantLib. It
requires patched version of Cython 0.15 (major patch) or 0.16 (minor patch).
You can find them both in the PyQL root directory.

Once Cython is patched, enter the pyql root directory. Open the setup.py file
and configure the Boost and QuantLib include and library directories, then run ::

python setup.py build


17 changes: 7 additions & 10 deletions docs/source/index.rst
Expand Up @@ -3,23 +3,20 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Quantlib cython wrapper's documentation!
========================================

The goal of this project is to create a lightweight, pythonic wrapper on top of
the QuantLib library.

Welcome to PyQL's documentation
===============================


Contents:

.. toctree::
:maxdepth: 2

business_dates
api
cython_wrapper
todo
getting_started
tutorial
users_guide
reference_guide
roadmap

Indices and tables
==================
Expand Down
8 changes: 8 additions & 0 deletions docs/source/reference_guide.rst
@@ -0,0 +1,8 @@
Reference guide
***************

.. include:: api.rst

.. include:: cython_wrapper.rst


19 changes: 19 additions & 0 deletions docs/source/roadmap.rst
@@ -0,0 +1,19 @@
Roadmap
=======

* Provide binary version for Mac, Windows and Linux
* Increase the Python coverage for C++ classes
* Make the API more pythonic and user friendly to abstract more of the complex
C++ constructions
* Provide a better integration for large datasets
* Investigate potential OpenMP support


Documentation
=============

List of online resources useful for the project:

* add examples from http://quantlib.org/slides/dima-ql-intro-1.pdf
* Fixed income - indexes (see http://quantlib.org/slides/dima-ql-intro-2.pdf
p78)
4 changes: 0 additions & 4 deletions docs/source/todo.rst

This file was deleted.

3 changes: 3 additions & 0 deletions docs/source/tutorial.rst
@@ -0,0 +1,3 @@
Tutorial
========

5 changes: 5 additions & 0 deletions docs/source/users_guide.rst
@@ -0,0 +1,5 @@
User's guide
************

.. include:: business_dates.rst

0 comments on commit b18256b

Please sign in to comment.