From 0d12d71920067be499d9237b4ad04f7f11047759 Mon Sep 17 00:00:00 2001 From: Cristian Maureira-Fredes Date: Fri, 13 Apr 2018 13:55:45 +0200 Subject: Add references from ApiExtractor to shiboken doc Including intersphinx extension allow us to link the documentation from ApiExtractor to shiboken's. ApiExtractor doc need to be build first, so we can use the inventory that sphinx create, to link it to shiboken's configuration. All the harcoded references were replaced by dynamic references. Also new labels were included to properly cross reference topics. Checked the spell on many rst files too. Task-number: PYSIDE-363 Change-Id: I11a50b1f9eee48a00a3de6f957942eb0823eba47 Reviewed-by: Alexandru Croitor --- sources/shiboken2/ApiExtractor/CMakeLists.txt | 2 +- .../ApiExtractor/doc/typesystem_arguments.rst | 20 +++++++++++++++++--- sources/shiboken2/doc/CMakeLists.txt | 2 +- sources/shiboken2/doc/codeinjectionsemantics.rst | 14 +++++--------- sources/shiboken2/doc/conf.py.in | 4 +++- sources/shiboken2/doc/faq.rst | 7 +++---- sources/shiboken2/doc/typeconverters.rst | 20 +++++++------------- sources/shiboken2/doc/typesystemvariables.rst | 7 ++----- 8 files changed, 39 insertions(+), 37 deletions(-) (limited to 'sources/shiboken2') 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 - + + // the code @@ -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 `. +.. _remove-argument: + remove-argument ^^^^^^^^^^^^^^^ @@ -48,6 +51,8 @@ remove-argument +.. _rename-to: + rename to ^^^^^^^^^ @@ -59,6 +64,7 @@ rename to +.. _remove-default-expression: remove-default-expression ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -72,6 +78,8 @@ remove-default-expression +.. _replace-default-expression: + replace-default-expression ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -85,6 +93,7 @@ replace-default-expression +.. _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" /> +.. _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 +.. _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 ` provides the +:ref:`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 ` +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 "" tag must be used. The details will be given later, but the gist of it are the tags -``_, which has only one conversion from C++ to Python, and -``_, that may define the conversion of multiple Python types +:ref:`native-to-target `, which has only one conversion from C++ to Python, and +:ref:`native-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 ``_, to directly return the +|project| expects the code for :ref:`native-to-target `, to directly return the Python result of the conversion, and the added conversions inside the -``_ must attribute the Python to C++ conversion result to +:ref:`target-to-native ` must attribute the Python to C++ conversion result to the :ref:`%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 ``_ tag and a custom check must be added. +an :ref:`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 ``_ are pretty much the same as for other type, +Converters for :ref:`container-type ` are pretty much the same as for other type, except that they make use of the type system variables :ref:`%INTYPE_# ` and :ref:`%OUTTYPE_# `. |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 @@ -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 ``_ +is gone, and the ``checkType`` is now an attribute of the :ref:`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. - -.. _``: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#native-to-target -.. _``: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#target-to-native -.. _``: 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 ` tag. To ease the binding developer +:ref:`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 ``_ type system tag. + with the :ref:`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; - - -.. _``: http://www.pyside.org/docs/apiextractor/typesystem_arguments.html#remove-default-expression -- cgit v1.2.3