From 05fbece36ead929b73446e55a2b72af50f66c907 Mon Sep 17 00:00:00 2001 From: "Gustavo J. A. M. Carneiro" Date: Thu, 17 Dec 2009 15:00:51 +0000 Subject: [PATCH] Even more sphinx documentation work --- .bzrignore | 3 + doc/Makefile | 3 + doc/apiref.rst | 33 ++++++++++ doc/codesink.rst | 10 +++ doc/conf.py | 2 +- doc/container.rst | 10 +++ doc/cppattribute.rst | 10 +++ doc/cppclass.rst | 2 +- doc/cppclass_typehandlers.rst | 10 +++ doc/cppexception.rst | 10 +++ doc/cppmethod.rst | 6 +- doc/enum.rst | 10 +++ doc/figures/Makefile | 13 ++++ doc/figures/work-flow-basic.dia | Bin 0 -> 2162 bytes doc/figures/work-flow-gccxml-apidefs.dia | Bin 0 -> 2636 bytes doc/figures/work-flow-gccxml.dia | Bin 0 -> 2378 bytes doc/gccxmlparser.rst | 14 +---- doc/index.rst | 11 +--- doc/module.rst | 6 +- doc/settings.rst | 10 +++ doc/tutorial.rst | 75 +++++++++++++++-------- doc/typehandlers.rst | 10 +++ doc/utils.rst | 2 +- 23 files changed, 196 insertions(+), 54 deletions(-) create mode 100644 doc/apiref.rst create mode 100644 doc/codesink.rst create mode 100644 doc/container.rst create mode 100644 doc/cppattribute.rst create mode 100644 doc/cppclass_typehandlers.rst create mode 100644 doc/cppexception.rst create mode 100644 doc/enum.rst create mode 100644 doc/figures/Makefile create mode 100644 doc/figures/work-flow-basic.dia create mode 100644 doc/figures/work-flow-gccxml-apidefs.dia create mode 100644 doc/figures/work-flow-gccxml.dia create mode 100644 doc/settings.rst create mode 100644 doc/typehandlers.rst diff --git a/.bzrignore b/.bzrignore index c05dce2..1208379 100644 --- a/.bzrignore +++ b/.bzrignore @@ -5,4 +5,7 @@ ./pybindgen/version.py ./doc/_build ./.waf-* +./doc/figures/work-flow-basic.png +./doc/figures/work-flow-gccxml-apidefs.png +./doc/figures/work-flow-gccxml.png diff --git a/doc/Makefile b/doc/Makefile index 387918c..ab25083 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -30,11 +30,13 @@ clean: -rm -rf _build/* html: + cd figures && $(MAKE) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html @echo @echo "Build finished. The HTML pages are in _build/html." dirhtml: + cd figures && $(MAKE) $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml @echo @echo "Build finished. The HTML pages are in _build/dirhtml." @@ -65,6 +67,7 @@ qthelp: @echo "# assistant -collectionFile _build/qthelp/PyBindGen.qhc" latex: + cd figures && $(MAKE) $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex @echo @echo "Build finished; the LaTeX files are in _build/latex." diff --git a/doc/apiref.rst b/doc/apiref.rst new file mode 100644 index 0000000..d8dfa5e --- /dev/null +++ b/doc/apiref.rst @@ -0,0 +1,33 @@ + +PyBindGen API Reference +======================= + + +Higher layers +----------------------- + +.. toctree:: + :maxdepth: 2 + + module + function + enum + cppclass + cppmethod + cppattribute + cppexception + container + + gccxmlparser + settings + + +Lower layers +----------------------- +.. toctree:: + :maxdepth: 2 + + utils + typehandlers + cppclass_typehandlers + codesink diff --git a/doc/codesink.rst b/doc/codesink.rst new file mode 100644 index 0000000..4ce4f7f --- /dev/null +++ b/doc/codesink.rst @@ -0,0 +1,10 @@ + +================================================================= +typehandlers.codesink: classes that receive generated source code +================================================================= + + +.. automodule:: pybindgen.typehandlers.codesink + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/conf.py b/doc/conf.py index f4015cc..02c31f1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -150,7 +150,7 @@ html_static_path = ['_static'] #html_split_index = False # If true, links to the reST sources are added to the pages. -html_show_sourcelink = False +html_show_sourcelink = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the diff --git a/doc/container.rst b/doc/container.rst new file mode 100644 index 0000000..ccf899f --- /dev/null +++ b/doc/container.rst @@ -0,0 +1,10 @@ + +========================================================== +container: wrap STL containers +========================================================== + + +.. automodule:: pybindgen.container + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/cppattribute.rst b/doc/cppattribute.rst new file mode 100644 index 0000000..9725725 --- /dev/null +++ b/doc/cppattribute.rst @@ -0,0 +1,10 @@ + +============================================== +cppattribute: wrap class/instance attributes +============================================== + + +.. automodule:: pybindgen.cppattribute + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/cppclass.rst b/doc/cppclass.rst index a0055b9..4508f19 100644 --- a/doc/cppclass.rst +++ b/doc/cppclass.rst @@ -1,6 +1,6 @@ ======================= -cppclass +cppclass: wrap C++ classes or C structures ======================= diff --git a/doc/cppclass_typehandlers.rst b/doc/cppclass_typehandlers.rst new file mode 100644 index 0000000..11249f0 --- /dev/null +++ b/doc/cppclass_typehandlers.rst @@ -0,0 +1,10 @@ + +======================= +cppclass_typehandlers: type handlers for C++ classes (or C structures) +======================= + + +.. automodule:: pybindgen.cppclass_typehandlers + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/cppexception.rst b/doc/cppexception.rst new file mode 100644 index 0000000..c11a15b --- /dev/null +++ b/doc/cppexception.rst @@ -0,0 +1,10 @@ + +============================================== +cppexceptions: translate C++ exceptions into Python +============================================== + + +.. automodule:: pybindgen.cppexception + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/cppmethod.rst b/doc/cppmethod.rst index 941f23d..b05b861 100644 --- a/doc/cppmethod.rst +++ b/doc/cppmethod.rst @@ -1,7 +1,7 @@ -============================== -cppmethod: C++ method wrappers -============================== +============================================== +cppmethod: wrap class methods and constructors +============================================== .. automodule:: pybindgen.cppmethod diff --git a/doc/enum.rst b/doc/enum.rst new file mode 100644 index 0000000..af89494 --- /dev/null +++ b/doc/enum.rst @@ -0,0 +1,10 @@ + +========================================================== +enum: wrap enumrations +========================================================== + + +.. automodule:: pybindgen.enum + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/figures/Makefile b/doc/figures/Makefile new file mode 100644 index 0000000..91652a0 --- /dev/null +++ b/doc/figures/Makefile @@ -0,0 +1,13 @@ + +figures_dia=$(shell echo *.dia) +figures_png=$(figures_dia:.dia=.png) + + +all: $(figures_png) + +%.png: %.dia + dia $< -e $@ + + +clean: + -rm -f $(figures_png) diff --git a/doc/figures/work-flow-basic.dia b/doc/figures/work-flow-basic.dia new file mode 100644 index 0000000000000000000000000000000000000000..ac1f16fccb4af3575d4efe2d7475243554c55c2e GIT binary patch literal 2162 zcmV-&2#xn2iwFP!000021MOW~Z{s!^efO^rJTJSbON$qYRNbW58DP+dDOzBrSfDQk zEityXvSdhfGVa6v_9Z1}64{b3lIbK}8kh|1&^#hVp7Y(P{P@$?W#Zh6yoj^(W(a{h zbVM3vQJl_ihQELL_&po`bUXMliun)f-#q6_M|~qL^t+qkLdw+-Ylc(#_pN%>OT3}-z2bDn4GG#XZ|w(Y_! z$#UnOCpW`)cjaq1-gYyt^>d)_6`zY)F8H7AUAyWP1YNpbiF~))+J5-dU(?050?8%M=W)7^rRFE8CIbNv2m0kh=3y66 z{5UV?!_BS>ms}Svzb;%{OjlVha~{im$XS*pf~OU#%-5njP7(4%EwMwxg57(+i>1tt zT>l+Uicw6 z&1JgZy*nj?KYhLDYN&c^m57K5Pk84`#C#n`qBye5>TOzjT5Ow*kInjSyHh8o`e;Y6 zONfMTM856*{gYHX+Z()P9EXQ8zJGl8Y)-P-e?%y^gZ-Ff58;C6()r$bpM4!Z86wII ziKCn0uWo&|cE_iBQ$)BoU90SAO?iMJ#zv3;;_c4EK8v)0%x1e7xf%vf=ZW}+LtR|r zVB}4Z3uxfu5%htNI^v2%ET>_Xr~5|3Wd~RSmF%)V$VX-&fDuHLdNJnGz@-rOz*>lS zzL4!;2)HD8{$kz0W?3GI{MgW3(De=#i|k?AV6Pq*;&V_|Jc{Zfyf=W3*DuA_y}PhW zNIPxXW}-AjYwdO{*VSegr_o%bEyn8s#&0tpvQ#!9>d&1!zKoNNx-gy=L#L1%O-+hb zs;~Yml6xWJkUwY8^RHlU9XH+_=GI@NA84KL8YzLP6+KeK;M0Ckbsaq5Fu86&AZ2CF z)1_#>pCVl^8w`X)CPI_SwJG)ZNtW7l>i1thDTVr1sQlXoje@;33Ia5OE(i?jQveVg zF#we|K@4CpQa^p#kvEn?@?*Ra#i2B*djSYMH6Ub8@(}P0YMcjfP2z%%V9Gxe#}y8G zbq+#3!1U%{=ll1+of6K0xQmnI1c-VB==I9pZ+WIo=w)lr#_HbXbg$%5tTvWsb?*|o z_gN`O#Pdjr-zT;68?+Dg);=vpF4XeJ0^g{IrjVegfiQ(=qC7L=DH()-K-^Jz!z@jw zB8|%NbQ)ztQy-uJ;;Ly!Crd4yaJ73mO<|T-D>Q0Sr##QIhh413P0^|6X(H13;la?l zLI=1nEQfVLjCip)K0LHzWI}_4d4TkeGp1{VF`q}!e_N;FLPX9NzIslba7&$}H+A}o zQ7{`(!;y4l05Mj<=r}rp+8RP2c*DVp{!@2Kzyd3gLC@yk6iD|OKLZ;@CE4T3?I?& z%S#9YSh_jBL1NM%u2-T=kPnz&x`+PTbr1W_+G)hunK?*+6hazMUO&#dpzPCHxUVnq5McRBHFP1maLQ%}=eh_CG7nsYsf52|58N5KP3S#=aFokA|Rgg|TXc%3s5-4Yj*0PRouv(?xyuG?| z6>E%HW6T<3ry66Q;#tn~&EQMsXoJieW5$bBJm9kGiB80xW3blP>#0_O=mH^mZ4nVb zkZ(93&pe_7VUYM_f&xGYgBsYwh?)<`Hx06(VE`~9RbJZ*Y^jP3$D4cl2Yh|;_!9`H z_X9wx(vd3T7R0Q3$vf&c&j literal 0 HcmV?d00001 diff --git a/doc/figures/work-flow-gccxml-apidefs.dia b/doc/figures/work-flow-gccxml-apidefs.dia new file mode 100644 index 0000000000000000000000000000000000000000..5fb3bccb204a6dbd4810f996f91ea885fe7b5e68 GIT binary patch literal 2636 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 literal 0 HcmV?d00001 diff --git a/doc/figures/work-flow-gccxml.dia b/doc/figures/work-flow-gccxml.dia new file mode 100644 index 0000000000000000000000000000000000000000..124a6d0f384f67dc416a89a9c3452769f55e5e6e GIT binary patch literal 2378 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 + + .. image:: figures/work-flow-gccxml.* + + 3. Automatically scan header files to generate API defs file, that + file can later be used to generate the bindings. See (see + :ref:`Header file scanning with (py)gccxml: python intermediate + file`); + + .. image:: figures/work-flow-gccxml-apidefs.* + + A simple example ================ -The best way to get a feel for what pybindgen looks like is to go through a +The best way to get a feel for what PyBindGen looks like is to go through a simple example. Let's assume that we have a simple C API as shown below declared in a header my-module.h: @@ -132,7 +157,6 @@ should be self-explanatory:: Wrapping types by value ======================= ---------------- Primitive types --------------- @@ -219,7 +243,6 @@ With the resulting python-visible API:: >>> MyModule.MyModuleDoAction (MyModule.CONSTANT_B) MyModuleDoAction: 1 --------------- Compound types -------------- @@ -259,8 +282,8 @@ from python:: struct.add_instance_attribute('b', 'int') The name of the method called here, 'add_instance_attribute' reflects the fact that -pybindgen can wrap both C and C++ APIs: in C++, there exist both instance and static -members so, pybindgen provides two methods: add_instance_attribute and add_static_attribute +PyBindGen can wrap both C and C++ APIs: in C++, there exist both instance and static +members so, PyBindGen provides two methods: add_instance_attribute and add_static_attribute to register these two kinds of members. Our C API then becomes accessible from python:: @@ -282,7 +305,6 @@ Our C API then becomes accessible from python:: -20 ------------ C++ classes ----------- @@ -384,7 +406,6 @@ The resulting python API reflects the underlying C++ API very closely:: >>> inner.Do(MyModule.Outer.INNER_A) --------------- C++ namespaces -------------- @@ -441,11 +462,10 @@ only by value but, a large fraction of real-world APIs use raw pointers (and, in the case of C++, smart pointers) as arguments or return values of functions/methods. -Rather than try to explain the detail of every option offered by pybindgen +Rather than try to explain the detail of every option offered by PyBindGen to deal with pointers, we will go through a couple of very classic memory management schemes and examples. ------------------------- Function returns pointer ------------------------ @@ -466,7 +486,7 @@ can write:: mod.add_function('DoSomethingAndReturnClass', retval('MyClass *', caller_owns_return=True), []) -The above will tell pybindgen that the caller (the python runtime) becomes +The above will tell PyBindGen that the caller (the python runtime) becomes responsible for deleting the instance of MyClass returned by the function DoSomethingAndReturnClass when it is done with it. @@ -539,7 +559,7 @@ To wrap this class, we first need to declare our class:: decref_method='Unref', peekref_method='PeekRef')) -The above allows pybindgen to maintain and track the reference count +The above allows PyBindGen to maintain and track the reference count of the MyClass object while the code below shows how we can declare a function taking a pointer as input:: @@ -569,12 +589,12 @@ While classic reference counting rules require that the callee returns a reference to the caller (i.e., it calls Ref on behalf of the caller before returning the pointer), some APIs will undoubtedly return a pointer and expect the caller to acquire a reference to the returned object by -calling Ref himself. Pybindgen hopefully can be made to support this +calling Ref himself. PyBindGen hopefully can be made to support this case too:: mod.add_function('DoSomething', retval('MyClass *', caller_owns_return=False), []) -Which instructs pybindgen that DoSomething is not to be trusted and that it should +Which instructs PyBindGen that DoSomething is not to be trusted and that it should acquire ownership of the returned pointer if it needs to keep track of it. @@ -582,7 +602,7 @@ A STL container --------------- If you have a function that takes a STL container, you have to -tell pybindgen to wrap the container first: +tell PyBindGen to wrap the container first: .. code-block:: c++ @@ -602,9 +622,12 @@ Is wrapped by:: .. ============================================== +Advanced usage +============== + Basic interface with error handling -=================================== +----------------------------------- It is also possible to declare a error handler. The error handler will be invoked for API definitions that cannot be wrapped for some @@ -658,7 +681,8 @@ Module.add_function() do that in a way that the error handler can be invoked and the function is simply not wrapped if the error handler says so. ------------------------------------- +.. _header-file-scanning: + Header file scanning with (py)gccxml ------------------------------------ @@ -688,7 +712,8 @@ The above script will generate the bindings for the module directly. It expects the input header file, a.h, as first command line argument. --------------------------------------------------------------- +.. _header-file-scanning-apidefs: + Header file scanning with (py)gccxml: python intermediate file -------------------------------------------------------------- diff --git a/doc/typehandlers.rst b/doc/typehandlers.rst new file mode 100644 index 0000000..2b875e5 --- /dev/null +++ b/doc/typehandlers.rst @@ -0,0 +1,10 @@ + +======================= +typehandlers.base: abstract base classes for type handlers and wrapper generators +======================= + + +.. automodule:: pybindgen.typehandlers.base + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/utils.rst b/doc/utils.rst index 7506b8e..8bf11be 100644 --- a/doc/utils.rst +++ b/doc/utils.rst @@ -1,6 +1,6 @@ ======================= -utils +utils: internal utilities =======================