diff options
| -rw-r--r-- | setup.py | 16 | ||||
| -rw-r--r-- | sources/shiboken2/ApiExtractor/CMakeLists.txt | 2 | ||||
| -rw-r--r-- | sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst | 20 | ||||
| -rw-r--r-- | sources/shiboken2/doc/CMakeLists.txt | 2 | ||||
| -rw-r--r-- | sources/shiboken2/doc/codeinjectionsemantics.rst | 14 | ||||
| -rw-r--r-- | sources/shiboken2/doc/conf.py.in | 4 | ||||
| -rw-r--r-- | sources/shiboken2/doc/faq.rst | 7 | ||||
| -rw-r--r-- | sources/shiboken2/doc/typeconverters.rst | 20 | ||||
| -rw-r--r-- | sources/shiboken2/doc/typesystemvariables.rst | 7 |
9 files changed, 50 insertions, 42 deletions
@@ -1293,11 +1293,17 @@ class pyside_build(_build): raise DistutilsSetupError("Error compiling {}".format(extension)) if extension.lower() == "shiboken2": - log.info("Generating Shiboken documentation {}...".format( - extension)) - if run_process([self.make_path, "doc"]) != 0: - raise DistutilsSetupError("Error generating documentation " - "{}".format(extension)) + try: + # Check if sphinx is installed to proceed + import sphinx + + log.info("Generating Shiboken documentation") + if run_process([self.make_path, "doc"]) != 0: + raise DistutilsSetupError( + "Error generating documentation {}".format(extension)) + except ImportError: + log.info("Sphinx not found, skipping documentation build") + if not OPTION_SKIP_MAKE_INSTALL: log.info("Installing module {}...".format(extension)) diff --git a/sources/shiboken2/ApiExtractor/CMakeLists.txt b/sources/shiboken2/ApiExtractor/CMakeLists.txt index 8d68b0dcf..a3301a068 100644 --- a/sources/shiboken2/ApiExtractor/CMakeLists.txt +++ b/sources/shiboken2/ApiExtractor/CMakeLists.txt @@ -63,7 +63,6 @@ parser/enumvalue.cpp set(APIEXTRACTOR_EXTRA_INCLUDES ${CLANG_EXTRA_INCLUDES}) set(APIEXTRACTOR_EXTRA_LIBRARIES ${CLANG_EXTRA_LIBRARIES}) -add_subdirectory(doc) if (NOT DISABLE_DOCSTRINGS) set(apiextractor_SRC ${apiextractor_SRC} @@ -92,6 +91,7 @@ include_directories(${CMAKE_CURRENT_SOURCE_DIR} ${Qt5Xml_INCLUDE_DIRS} ) +add_subdirectory(doc) add_library(apiextractor STATIC ${apiextractor_SRC} ${apiextractor_RCCS_SRC}) target_link_libraries(apiextractor ${Qt5Xml_LIBRARIES} diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst index 16e0678d3..28a5c80bc 100644 --- a/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst @@ -3,17 +3,18 @@ Modifying Arguments ------------------- -.. _conversion-rule: +.. _conversionrule: conversion-rule ^^^^^^^^^^^^^^^ The conversion-rule node allows you to write customized code to convert - the given argument between the target language and C++, and it is a child of the modify-argument node. + the given argument between the target language and C++, and it is a child of the modify-argument node: .. code-block:: xml - <modify-argument ...> + <modify-argument index="2"> + <!-- for the second argument of the function --> <conversion-rule class="target | native"> // the code </conversion-rule> @@ -36,6 +37,8 @@ conversion-rule .. note:: You can also use the conversion-rule node to specify :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-on-types>`. +.. _remove-argument: + remove-argument ^^^^^^^^^^^^^^^ @@ -48,6 +51,8 @@ remove-argument <remove-argument /> </modify-argument> +.. _rename-to: + rename to ^^^^^^^^^ @@ -59,6 +64,7 @@ rename to <rename to='...' /> </modify-argument> +.. _remove-default-expression: remove-default-expression ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -72,6 +78,8 @@ remove-default-expression <remove-default-expression /> </modify-argument> +.. _replace-default-expression: + replace-default-expression ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -85,6 +93,7 @@ replace-default-expression <replace-default-expression with="..." /> </modify-argument> +.. _replace-type: replace-type ^^^^^^^^^^^^ @@ -103,6 +112,8 @@ replace-type the fully qualified name (including name of the package as well as the class name). +.. _define-ownership: + define-ownership ^^^^^^^^^^^^^^^^ @@ -126,6 +137,7 @@ define-ownership owner="target | c++ | default" /> </modify-argument> +.. _reference-count: reference-count ^^^^^^^^^^^^^^^ @@ -161,6 +173,7 @@ reference-count The variable-name attribute specifies the name used for the variable that holds the reference(s). +.. _replace-value: replace-value ^^^^^^^^^^^^^ @@ -173,6 +186,7 @@ replace-value <modify-argument index="0" replace-value="this"/> +.. _parent: parent ^^^^^^ diff --git a/sources/shiboken2/doc/CMakeLists.txt b/sources/shiboken2/doc/CMakeLists.txt index 7bd0161ad..bb5ad8607 100644 --- a/sources/shiboken2/doc/CMakeLists.txt +++ b/sources/shiboken2/doc/CMakeLists.txt @@ -1,10 +1,10 @@ - find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.") if (SPHINX) message("-- sphinx-build - found") configure_file(conf.py.in conf.py @ONLY) add_custom_target(doc ${SPHINX} -b html -c . ${CMAKE_CURRENT_SOURCE_DIR} html ) + add_dependencies(doc doc_apiextractor) else() message("-- sphinx-build - not found! doc target disabled") if (WIN32) diff --git a/sources/shiboken2/doc/codeinjectionsemantics.rst b/sources/shiboken2/doc/codeinjectionsemantics.rst index bf3ddbe5e..0051c63df 100644 --- a/sources/shiboken2/doc/codeinjectionsemantics.rst +++ b/sources/shiboken2/doc/codeinjectionsemantics.rst @@ -2,12 +2,11 @@ Code Injection Semantics ************************ -API Extractor provides the `inject-code`_ tag allowing the user to put custom -written code to on specific locations of the generated code. -Yet this is only part of what is needed to generate proper binding code, where -the custom code should be written to depends upon the technology used on the -generated binding code. - +:std:doc:`API Extractor <apiextractor:overview>` provides the +:ref:`inject-code <apiextractor:inject-code>` tag +allowing the user to put custom written code to on specific locations of the generated code. +Yet this is only part of what is needed to generate proper binding code, where the custom code +should be written to depends upon the technology used on the generated binding code. This is the ``inject-code`` tag options that matters to |project|. @@ -396,6 +395,3 @@ to prevent bad custom code to pass unnoticed. (...) // Start of ``MODULENAME_module_wrapper.cpp`` - - -.. _`inject-code`: http://www.pyside.org/docs/apiextractor/typesystem_manipulating_objects.html#inject-code diff --git a/sources/shiboken2/doc/conf.py.in b/sources/shiboken2/doc/conf.py.in index 5dc7b868d..57c2f94b9 100644 --- a/sources/shiboken2/doc/conf.py.in +++ b/sources/shiboken2/doc/conf.py.in @@ -22,7 +22,8 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.coverage'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', +'sphinx.ext.coverage', 'sphinx.ext.intersphinx'] rst_epilog = """ .. |project| replace:: Shiboken @@ -158,3 +159,4 @@ html_show_sourcelink = False # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = '' +intersphinx_mapping = {'apiextractor': ('@CMAKE_BINARY_DIR@/ApiExtractor/doc/html','@CMAKE_BINARY_DIR@/ApiExtractor/doc/html/objects.inv')} diff --git a/sources/shiboken2/doc/faq.rst b/sources/shiboken2/doc/faq.rst index 4b2bf9eea..3653b8654 100644 --- a/sources/shiboken2/doc/faq.rst +++ b/sources/shiboken2/doc/faq.rst @@ -11,7 +11,7 @@ General What is Shiboken? ----------------- -Shiboken is a `GeneratorRunner`_ that outputs C++ code for CPython +Shiboken is a Generator Runner plugin that outputs C++ code for CPython extensions. The first version of PySide had source code based on Boost templates. It was easier to produce code but a paradigm change was needed, as the next @@ -45,7 +45,8 @@ What do I have to do to create my bindings? ------------------------------------------- Most of the work is already done by the API Extractor. -The developer creates a `typesystem`_ file with any customization wanted in +The developer creates a :std:doc:`typesystem <apiextractor:typesystem>` +file with any customization wanted in the generated code, like removing classes or changing method signatures. The generator will output the *.h* and *.cpp* files with the CPython code that will wrap the target library for python. @@ -68,5 +69,3 @@ That's how we call customized code that will be *injected* into the generated at specific locations. They are specified inside the typesystem. .. _`Mailing list`: http://lists.qt-project.org/mailman/listinfo/pyside -.. _`GeneratorRunner`: http://www.pyside.org/home-binding/binding-generator -.. _`typesystem`: http://www.pyside.org/docs/apiextractor/typesystem.html diff --git a/sources/shiboken2/doc/typeconverters.rst b/sources/shiboken2/doc/typeconverters.rst index ea32c7f0c..6b29bdb4f 100644 --- a/sources/shiboken2/doc/typeconverters.rst +++ b/sources/shiboken2/doc/typeconverters.rst @@ -58,22 +58,22 @@ the "<conversion-rule>" tag must be used. The details will be given later, but the gist of it are the tags -`<native-to-target>`_, which has only one conversion from C++ to Python, and -`<target-to-native>`_, that may define the conversion of multiple Python types +:ref:`native-to-target <apiextractor:native-to-target>`, which has only one conversion from C++ to Python, and +:ref:`native-to-native <apiextractor:target-to-native>`, that may define the conversion of multiple Python types to C++'s "Complex" type. .. image:: images/converter.png :height: 240px :align: center -|project| expects the code for `<native-to-target>`_, to directly return the +|project| expects the code for :ref:`native-to-target <apiextractor:native-to-target>`, to directly return the Python result of the conversion, and the added conversions inside the -`<target-to-native>`_ must attribute the Python to C++ conversion result to +:ref:`target-to-native <apiextractor:target-to-native>` must attribute the Python to C++ conversion result to the :ref:`%out <out>` variable. Expanding on the last example, if the binding developer want a Python 2-tuple of numbers to be accepted by wrapped C++ functions with "Complex" arguments, -an `<add-conversion>`_ tag and a custom check must be added. +an :ref:`add-conversion <apiextractor:add-conversion>` tag and a custom check must be added. Here's how to do it: .. code-block:: xml @@ -130,14 +130,12 @@ Here's how to do it: Container Conversions ===================== -Converters for `<container-type>`_ are pretty much the same as for other type, +Converters for :ref:`container-type <apiextractor:container-type>` are pretty much the same as for other type, except that they make use of the type system variables :ref:`%INTYPE_# <intype_n>` and :ref:`%OUTTYPE_# <outtype_n>`. |project| combines the conversion code for containers with the conversion defined (or automatically generated) for the containers. -.. _`container-type`: http://www.pyside.org/docs/apiextractor/typesystem_specifying_types.html#container-type - .. code-block:: xml <container-type name="std::map" type="map"> @@ -288,10 +286,6 @@ In this case, the parts of the implementation that will be used in the new conversion-rule are the ones in the two last method ``static inline PyObject* toPython(const Complex& cpx)`` and ``static inline Complex toCpp(PyObject* pyobj)``. The ``isConvertible`` method -is gone, and the ``checkType`` is now an attribute of the `<add-conversion>`_ +is gone, and the ``checkType`` is now an attribute of the :ref:`add-conversion <apiextractor:add-conversion>` tag. Refer back to the first example in this page and you will be able to correlate the above template with the new scheme of conversion rule definition. - -.. _`<native-to-target>`: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#native-to-target -.. _`<target-to-native>`: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#target-to-native -.. _`<add-conversion>`: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#add-conversion diff --git a/sources/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystemvariables.rst index 9de2b02f5..e595f7ddc 100644 --- a/sources/shiboken2/doc/typesystemvariables.rst +++ b/sources/shiboken2/doc/typesystemvariables.rst @@ -3,7 +3,7 @@ Type System Variables ********************* User written code can be placed in arbitrary places using the -:doc:`inject-code <codeinjectionsemantics>` tag. To ease the binding developer +:ref:`inject-code <apiextractor:inject-code>` tag. To ease the binding developer work, the injected code can make use of special variables that will be replaced by the correct values. This also shields the developer from some |project| implementation specifics. @@ -59,7 +59,7 @@ Variables system), this value will be inserted in the argument list. If you want to remove the argument so completely that it doesn't appear in any form on the ``%ARGUMENT_NAMES`` replacement, don't forget to remove also its default value - with the `<remove-default-expression/>`_ type system tag. + with the :ref:`remove-default-expression <apiextractor:remove-default-expression>` type system tag. Take the following method and related type system description as an example: @@ -332,6 +332,3 @@ that expects a Python sequence instead. delete[] argv; </inject-code> </modify-function> - - -.. _`<remove-default-expression/>`: http://www.pyside.org/docs/apiextractor/typesystem_arguments.html#remove-default-expression |