doxysip 0.1__tar.gz

doxysip-0.1/DOCUMENTATION.rst

@@ -0,0 +1,194 @@
+Documentation
+=============
+
+
+Getting Started
+---------------
+
+This how-to assumes we have a C++ code documented with Doxygen and a SIP project with
+specification files (`.sip`) to bind this C++ code in Python.
+Doxygen must be configured to produce XML output.
+
+
+1. Install Doxy-SIP in the Python environment alongside Sphinx:
+
+   .. code-block:: bash
+
+       pip install doxysip
+
+2. Add Doxy-SIP to the list of loaded extensions in the Sphinx ``conf.py`` file:
+
+   .. code-block:: py
+
+          extensions = [
+           ...,
+           'doxysip',
+          ]
+
+3. Add the required parameters in the Sphinx ``conf.py`` file:
+
+   .. code-block:: py
+
+      sip_toml_project = "path/to/sip/project"
+      sip_doxygen_project = "path/to/doxygen/xml/output"
+
+4. Start using the doxysip directives in the doc source files to insert object documentation.
+
+
+Extension configuration options
+-------------------------------
+
+**sip_toml_project** :
+   This option must contain a path to the directory containing the SIP project ``pyproject.toml``
+   that defines the binding modules.
+
+**sip_doxygen_project** :
+   This option must contain a path to the directory containing the XML output produced by Doxygen.
+
+
+Docstring tags
+--------------
+
+If description data exists in both C++ and docstrings for the same object,
+Doxy-SIP will combine the two according to an optional tag, present in
+the first line of the docstring.
+This tag does not appear in the final documentation text.
+
+The SIP specification file should look like this::
+
+   %Docstring
+       \dox:[prepend|append|discard]
+       First line of description
+   %End
+
+Tag values:
+
+* `prepend` : the C++ description is added before the docstring content.
+* `append` : the C++ description is added after the docstring content.
+* `discard` (default) : the C++ data is discarded.
+
+Notes:
+
+- In the case of functions and methods, the arguments and result descriptions in C++ data (from
+  \\param or \\return tags) are kept if no tag is present, and is always placed after the
+  function description, regardless of the tag value.
+- The docstring is processes as regular reStructuredText content so markup can be used.
+
+
+Directives
+----------
+
+`..sip:specification:: [name]`
+******************************
+
+This directive sets the currently loaded SIP module specification. The name must be fully qualified.
+
+Note: It must be used before any other Doxy-SIP directive. All other directives work with the module
+loaded using this directive.
+
+
+`..sip:module::`
+****************
+
+This directive inserts the content of the current module docstring.
+
+
+`..sip:class:: [name]`
+**********************
+
+This directive inserts the description for the class defined in the current module.
+
+Options:
+   
+   `:members`: [filters]
+      Insert the documentation of the class members : sub-classes, methods, attributes, etc.
+       
+      [filters] defines the filtering rules for displaying members. See the dedicated section below.
+
+   `:no-header`:
+      If set, the class header (class name, qualifiers and inheritance) is not generated and the content
+      for the class members (if generated) is not indented.
+
+   `:no-doc`:
+      If set, the class description is not generated.
+
+
+`..sip:namespace:: [name]`
+**************************
+
+Namespaces are implemented by SIP as regular classes. To differentiate them, a ``[namespace]`` tag is added
+as prefix to the class signature.
+
+Options are the same as for ``..sip:class::``
+
+
+`..sip:property:: [name]`
+*************************
+
+This directive describes a Python class property.
+
+
+`..sip:enum:: [name]`
+*********************
+
+This directive describes an enumeration class.
+
+
+`..sip:method:: [name]`
+***********************
+
+This directive describes a method.
+
+
+`..sip:variable:: [name]`
+*************************
+
+This directive describes a variable/attribute.
+
+
+`..sip:macro-constant:: [var_name] [macro_name]`
+************************************************
+
+This directive describes a C++ constant defined by a macro, and implemented in Python
+as a constant global variable.
+
+**var_name** : Python variable name
+
+**macro_name** (optional): C++ macro name, if different from the Python variable name.
+
+
+Member filtering
+----------------
+
+By defaults, the ``:member:`` option will display class/namespace members that are
+*public* and documented (either in Doxygen or in SIP docstrings).
+To add other members, filtering flags must be added as::
+
+   :members: [undoc|private|special|all]
+
+The following member filters are define:
+
+- ``undoc`` : if specified, undocumented members will be displayed.
+- ``private`` : if specified, private members (i.e. with a Python name starting by an underscore)
+  will be displayed.
+- ``special`` : if specified, special methods (i.e. with a Python name starting and ending
+  with a double underscore) will be displayed.
+- ``all`` : if specified, all members will be displayed.
+
+Notes:
+
+* If several flags are specified, they are separated by a comma. Example: ``:members: undoc,private``
+* An undocumented private member requires both ``undoc`` and ``private`` to be displayed. Idem for
+  an undocumented special method, both ``undoc`` and ``special`` are required.
+
+A special filtering rule applies to constructors when displayed as part of a sip:class directive:
+
+   By default, SIP generates automatically *default* constructors for each class, where possible:
+   the no-argument constructor (``Class()``) and the copy constructor
+   (C++: ``Class(const Class&)``, Python: ``Class(a0: Class)``).
+   
+   If the class has only *default* constructors, then they are only displayed if they are documented
+   (or the ``undoc`` flag is specified).
+   
+   If the class has any *non-default* constructors, then all constructors are displayed, whether they're
+   documented or not.

doxysip-0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, C. Savergne <csavergne@yahoo.com>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

doxysip-0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+#Excluded pycache
+global-exclude *.pyc
+
+include DOCUMENTATION.rst

doxysip-0.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: doxysip
+Version: 0.1
+Summary: A Sphinx extension for semi-automatic class documentation from SIP bindings and Doxygen
+Author-email: "C. Savergne" <csavergne@yahoo.com>
+License-Expression: BSD-3-Clause
+Project-URL: homepage, https://github.com/clesav/doxy-sip
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: sphinx>=7.2
+Requires-Dist: sip<6.16,>=6.13
+Dynamic: license-file
+
+Doxy-SIP
+========
+
+
+Doxy-SIP is a Sphinx plugin providing integration between
+Doxygen, the SIP bindings tools and Sphinx.
+
+The itch to scratch
+-------------------
+
+When writing Python compiled extensions created in C++ and SIP bindings, options to
+write clean and easy documentation that can be integrated in Sphinx-produced web pages
+are limited:
+
+* Using Doxygen comments in the C++ code:
+
+    Ddocumenting an API within the C++ source files is very easy and tools such as Breathe. However,
+    using tools such as Breathe will produce an API with C++ signature whereas Python
+    signatures are different, omit certain C++ objects or add new ones.
+
+* Using Python Docstrings:
+
+    It limits the functionalities and defeats the philosophy of writing documentation
+    and code in the same place.
+
+* Manually documenting in RST files:
+
+    Just too tedious.
+
+Doxy-SIP attempts to resolve that by combining Doxygen output and docstring in SIP
+specification files to provide clear documentation about the C++ implementation, but with
+a Pythonic presentation.
+
+It takes as input:
+
+* A Doxygen output in XML format documenting C++ code.
+* A SIP project file (pyproject.toml) defining the bindings for the same C++ code.
+
+It defines a new Sphinx domain (sip) and directives to semi-automatically (à la sphinx.ext.autodoc)
+add documentation on objects defined in the bindings specification files.
+
+Installation
+------------
+
+Breathe is available from github and PyPI <https://pypi.org/project/doxy-sip/>. It can be installed with::
+
+    pip install doxysip
+
+Documentation
+-------------
+
+Short documentation - <https://github.com/clesav/doxy-sip/blob/main/DOCUMENTATION.rst>.
+
+Requirements
+------------
+
+Doxy-SIP requires Python 3.9+, Sphinx 7.2+, Doxygen 1.9.2+ and SIP 6.13+
+
+Acknowledgements
+----------------
+
+- Dimitri van Heesch for Doxygen - <https://www.doxygen.nl>.
+- Georg Brandl for Sphinx - <https://www.sphinx-doc.org>.
+- Phil Thompson for SIP - <https://github.com/Python-SIP/sip>.
+

doxysip-0.1/README.rst

@@ -0,0 +1,65 @@
+Doxy-SIP
+========
+
+
+Doxy-SIP is a Sphinx plugin providing integration between
+Doxygen, the SIP bindings tools and Sphinx.
+
+The itch to scratch
+-------------------
+
+When writing Python compiled extensions created in C++ and SIP bindings, options to
+write clean and easy documentation that can be integrated in Sphinx-produced web pages
+are limited:
+
+* Using Doxygen comments in the C++ code:
+
+    Ddocumenting an API within the C++ source files is very easy and tools such as Breathe. However,
+    using tools such as Breathe will produce an API with C++ signature whereas Python
+    signatures are different, omit certain C++ objects or add new ones.
+
+* Using Python Docstrings:
+
+    It limits the functionalities and defeats the philosophy of writing documentation
+    and code in the same place.
+
+* Manually documenting in RST files:
+
+    Just too tedious.
+
+Doxy-SIP attempts to resolve that by combining Doxygen output and docstring in SIP
+specification files to provide clear documentation about the C++ implementation, but with
+a Pythonic presentation.
+
+It takes as input:
+
+* A Doxygen output in XML format documenting C++ code.
+* A SIP project file (pyproject.toml) defining the bindings for the same C++ code.
+
+It defines a new Sphinx domain (sip) and directives to semi-automatically (à la sphinx.ext.autodoc)
+add documentation on objects defined in the bindings specification files.
+
+Installation
+------------
+
+Breathe is available from github and PyPI <https://pypi.org/project/doxy-sip/>. It can be installed with::
+
+    pip install doxysip
+
+Documentation
+-------------
+
+Short documentation - <https://github.com/clesav/doxy-sip/blob/main/DOCUMENTATION.rst>.
+
+Requirements
+------------
+
+Doxy-SIP requires Python 3.9+, Sphinx 7.2+, Doxygen 1.9.2+ and SIP 6.13+
+
+Acknowledgements
+----------------
+
+- Dimitri van Heesch for Doxygen - <https://www.doxygen.nl>.
+- Georg Brandl for Sphinx - <https://www.sphinx-doc.org>.
+- Phil Thompson for SIP - <https://github.com/Python-SIP/sip>.
+

doxysip-0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=75.4"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "doxysip"
+description = "A Sphinx extension for semi-automatic class documentation from SIP bindings and Doxygen"
+readme = "README.rst"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = ["sphinx>=7.2", "sip>=6.13,<6.16"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Documentation :: Sphinx",
+    "Topic :: Software Development :: Documentation",
+]
+urls.homepage = "https://github.com/clesav/doxy-sip"
+
+version = "0.1"
+
+
+[[project.authors]]
+name = "C. Savergne"
+email = "csavergne@yahoo.com"
+

doxysip-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

doxysip-0.1/src/doxysip/__init__.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+# Copyright (c) 2026 C. Savergne <csavergne@yahoo.com>
+
+
+from sphinx.domains import Domain
+
+from .directives import (
+    SIPSpecificationDirective,
+    SIPModuleDirective,
+    SIPClassDirective,
+    SIPNamespaceDirective,
+    SIPEnumDirective,
+    SIPMethodDirective,
+    SIPPropertyDirective,
+    SIPVariableDirective,
+    SIPMacroConstantDirective,
+)
+
+
+__version__ = "0.0.1"
+
+
+class SIPDomain(Domain):
+    name = 'sip'
+    label = 'Bindings specification language'
+    directives = {
+        'specification': SIPSpecificationDirective,
+        'module' : SIPModuleDirective,
+        'class': SIPClassDirective,
+        'namespace': SIPNamespaceDirective,
+        'enum': SIPEnumDirective,
+        'method': SIPMethodDirective,
+        'property': SIPPropertyDirective,
+        'variable': SIPVariableDirective,
+        'macro-constant': SIPMacroConstantDirective,
+    }
+    initial_data = {
+        'sip_specs': {},
+        'sip_dox_index': None,
+        'sip_project_loaded': False,
+        'sip_current_spec': '',
+    }
+
+
+def setup(app):
+    app.add_domain(SIPDomain)
+    app.add_config_value('sip_toml_project', '.', 'env', str)
+    app.add_config_value('sip_doxygen_project', '.', 'env', str)
+
+    return {
+        "version": __version__
+    }