Update documentation

Author: virtuald

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Dustin Spicuzza <[email protected]>, All rights reserved.
+Copyright (c) 2020-2025 Dustin Spicuzza <[email protected]>, All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -1,13 +1,14 @@
 semiwrap
 ========
 
-This is a build tool intended to be generally useful for any python project
-that has binary dependencies. It is especially designed to meet the needs
-of RobotPy's various wrapper libraries, chiefly around:
+semiwrap is a build tool that makes it simpler to wrap C/C++ libraries with
+pybind11 by automating large portions of the wrapping process and handling some
+of the more complex aspects of creating pybind11 based wrappers (especially with
+trampolines to allow inheriting from C++ classes from Python).
 
-* Managing upstream binary dependencies
-* Autogenerating pybind11 wrappers around those dependencies
-* Building wheels from those generated wrappers
+semiwrap includes a hatchling plugin that autogenerates `meson.build` files that
+can be built using meson, and those build files parse your wrapped headers and
+generate/compile pybind11 based wrappers into python extension modules. 
 
 Requires Python 3.8+
 
@@ -21,8 +22,8 @@ Author
 
 Dustin Spicuzza is the primary author of semiwrap.
 
-Semiwrap is a direct decendant of the robotpy-build project, and is
-culmination of many years of experimentation with automated wrapper
-generation by members of the RobotPy community.
+Semiwrap is a direct decendant of the robotpy-build project, and is culmination
+of many years of experimentation with automated wrapper generation by members of
+the RobotPy community.
 
 semiwrap is available under the BSD 3-clause license.

docs/autowrap.rst

@@ -4,7 +4,7 @@
 Automated C++ header wrapping
 =============================
 
-robotpy-build can be told to parse C/C++ headers and automatically generate 
+semiwrap can be told to parse C/C++ headers and automatically generate 
 :std:doc:`pybind11 <pybind11:basics>` wrappers around the functions
 and objects found in that header.
 
@@ -15,9 +15,9 @@ and objects found in that header.
 C++ Features
 ------------
 
-robotpy-build uses a pure python C++ parser and macro processor to attempt to
+semiwrap uses a pure python C++ parser and macro processor to attempt to
 parse header files. As a result, a full AST of the header files is not created.
-This means particularly opaque code might confuse the parser, as robotpy-build
+This means particularly opaque code might confuse the parser, as semiwrap
 only receives the names, not the actual type information.
 
 However, most basic features typically work without needing to coerce the
@@ -34,6 +34,7 @@ generator into working correctly, including:
 * final classes/methods - cannot be overridden from Python code
 * Enumerations
 * Global variables
+* Many many more weird edge cases too
 
 Additionally, the following features are supported, but require some manual
 intervention:
@@ -46,22 +47,22 @@ to your package in ``pyproject.toml``:
 
 .. code-block:: toml
 
-    [tool.robotpy-build.wrappers."MYPACKAGE".autogen_headers]
+    [tool.semiwrap.extension_modules."PACKAGE.NAME".headers]
     demo = "demo.h"
 
 That causes ``demo.h`` to be parsed and wrapped.
 
 .. note:: If you're importing a large number of headers, the
-          ``robotpy-build scan-headers`` tool can generate this for you
+          ``semiwrap scan-headers`` tool can generate this list for you
           automatically.
 
 Documentation
 -------------
 
-robotpy-build will find doxygen documentation comments on many types of elements
-and use sphinxify to translate them into python docstrings. All elements that
-support documentation strings can have their docstrings set explicitly using 
-a ``doc`` value in the YAML file.
+semiwrap will find doxygen documentation comments on many types of elements
+and use sphinxify to translate them into python docstrings. If this is not
+sufficient, all elements that support documentation strings can have their
+docstrings set explicitly using a ``doc`` value in the YAML file.
 
 .. code-block:: yaml
 

docs/conf.py

@@ -26,7 +26,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "semiwrap"
-copyright = "2020, RobotPy Development Team"
+copyright = "2025, RobotPy Development Team"
 author = "RobotPy Development Team"
 
 # The full version, including alpha/beta/rc tags

docs/config/autowrap.rst

@@ -4,66 +4,68 @@
 Generator Customization
 =======================
 
-Because robotpy-build's code generation is intended to be a semi-automated
+Because semiwrap's code generation is intended to be a semi-automated
 process (except for simple C++ code), a rich set of per-{class/function/parameter}
 configuration options can be specified in per-file YAML configurations.
 
 Additionally, some headers are too complex for the autogenerator to
 completely process, so when this occurs you must manually specify required
 information in the YAML file.
 
-Most files generated by robotpy-build are customizable.
+Most files generated by semiwrap are customizable.
 
-.. note:: robotpy-build is designed for the RobotPy project and may contain
+.. note:: semiwrap is designed for the RobotPy project and may contain
           defaults that aren't appropriate for all projects. If you find that
           you need more customization, file an issue on github and let's talk
           about it!
 
 Location of customization file
 ------------------------------
 
-In your ``pyproject.toml``, you can specify either a single YAML file with
-customizations, or you can specify a directory that robotpy-build will search
-for YAML files.
-
-Single file:
-
-.. code-block:: toml
-
-   [tool.robotpy-build.wrappers."PACKAGENAME"]
-   generation_data = "gen/data.yml"
-
-Multiple files:
+By default customization files are located in the ``semiwrap`` directory. The name
+of the YAML file is the ``key`` in the extension module headers table:
 
 .. code-block:: toml
 
-   [tool.robotpy-build.wrappers."PACKAGENAME"]
-   generation_data = "gen"
-
-When a directory is specified, pybind11 will search for YAML files in the
-directory based on the header filename. In the above example, customization
-data for ``header.h`` could be specified in ``gen/header.yml``.
+   [tool.semiwrap.extension_modules."PACKAGE.NAME".headers]
+   # yaml file is `semiwrap/demo.yml`
+   demo = "include/demo.h"
 
 
 Autogeneration
 --------------
 
-The default values for these YAML files can be generated via the robotpy-build
-command line tool:
+The default values for these YAML files should be generated via the semiwrap command
+line tool:
 
 .. code-block:: sh
 
-   robotpy-build create-gen --write
+   semiwrap create-yaml --write
 
 This can be a good way to get the boilerplate out of the way when you need to
 provide customizations.
 
+Manual pybind11 APIs
+--------------------
+
+You can write your own custom .cpp files and add them to the python extensions
+generated by semiwrap. In your ``meson.build`` after you include the generated
+``semiwrap`` subdir, add files to ``NAME_sources``.
+
+.. code-block:: meson
+
+   subdir('semiwrap')
+
+   my_module_sources += files(
+      'src/my_module/main.cpp',
+   )
+
+
 Reference
 ---------
 
 The following strctures describe the dictionaries that are read from the YAML
-file. The toplevel structure is :class:`.AutowrapConfigYaml`.
+files. The toplevel structure is :class:`.AutowrapConfigYaml`.
 
-.. automodule:: robotpy_build.config.autowrap_yml
+.. automodule:: semiwrap.config.autowrap_yml
    :members:
-   :undoc-members:

docs/config/pyproject.rst

@@ -1,40 +1,26 @@
 
 .. _pyproject:
 
-setup.py and pyproject.toml
-===========================
-
-setup.py
---------
-
-Projects that use robotpy-build must use the setup function provided by
-robotpy-build. Your project's setup.py should look like this:
-
-.. code-block:: py
-
-   #!/usr/bin/env python3
-   from robotpy_build.setup import setup
-   setup()
-
 pyproject.toml
---------------
+==============
 
-Projects that use robotpy-build must add a ``pyproject.toml`` to the root of
+Projects that use semiwrap must add a ``pyproject.toml`` to the root of
 their project as specified in `PEP 518 <https://www.python.org/dev/peps/pep-0518>`_.
 
-It is recommended that projects include the standard ``build-system`` section to
-tell pip to install robotpy-build (and any other dependencies) before starting
-a build.
+Because semiwrap is a hatchling plugin, you should add semiwrap and hatchling
+to your ``build-system.requires``. You need meson to build the project, so we
+recommend also using ``hatch-meson`` to do so.
 
 .. code-block:: toml
 
    [build-system]
-   requires = ["robotpy-build>=2020.1.0,<2021.0.0"]
+   build-backend = "hatchling.build"
+   requires = ["semiwrap", "hatch-meson", "hatchling"]
 
-Projects must include robotpy-build specific sections in their pyproject.toml.
-robotpy-build takes ``pyproject.toml`` and converts it to a python dictionary
-using ``toml.load``. The resulting dictionary is given to pydantic, which
-validates the structure of the dictionary against the objects described below.
+Projects must include semiwrap specific sections in their pyproject.toml.
+semiwrap takes ``pyproject.toml`` and converts it to a python dictionary
+using ``toml.load``. The resulting dictionary is converted to the dataclasses
+described below.
 
 Required sections:
 
@@ -49,73 +35,12 @@ Optional sections:
 * :class:`.PatchInfo` - patch downloaded sources
 
 
-.. note:: For a complete example pyproject.toml file, see ``tests/cpp/pyproject.toml.tmpl``
-
-.. _pyproject_overrides:
-
-Overrides
----------
-
-You can define 'override' sections that will be grafted onto the configuration
-if they match a particular platform. For example, to change the dependencies
-for a wrapper section on Windows:
-
-.. code-block:: toml
-
-   [tool.robotpy-build.wrappers."PACKAGENAME".override.os_windows]
-   depends = ["windows-thing"]
-
-Any element in the robotpy-build section of pyproject.toml can be overridden
-by specifying the identical section as '.override.KEYNAME'. If the key matches
-the current configuration, the override will be written to the original section.
-The matched keys are generated at runtime. Current supported platform override
-keys are:
-
-* ``arch_{platform_arch}``
-* ``os_{platform_os}``
-* ``platform_{platform_os}_{platform_arch}``
-
-To get information about the current platform, you can run:
-
-.. code-block:: sh
-
-   robotpy-build platform-info
-
-To show the available platforms:
-
-.. code-block:: sh
-
-   robotpy-build platform-info --list
-
-To process a pyproject.toml and see the result of applying various overrides,
-you can use this tool to process for the current platform:
-
-.. code-block:: sh
-
-   robotpy-build show-override
-
-To show what would be processed for a different platform:
-
-.. code-block:: sh
-
-   robotpy-build show-override -p linux-athena
-
-.. _platforms:
-
-Current supported platform/os/arch combinations are:
-
-* OS: windows/osx/linux
-* Arch: x86/x86-64/armv7l/aarch64
-
-For ARM linux distributions we support:
+.. note:: For a complete example pyproject.toml file, see ``tests/cpp/*/pyproject.toml``
 
-* armv7l + nilrt (RoboRIO)
-* armv7l + raspbian (Raspbian 10)
-* aarch64 + bionic (Ubuntu 18.04)
 
 Reference
 ---------
 
-.. automodule:: robotpy_build.config.pyproject_toml
+.. automodule:: semiwrap.config.pyproject_toml
    :members:
    :exclude-members: __init__, Config