Update documentation

Author: virtuald

README.md

@@ -2,8 +2,17 @@ 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:
+that wants to use pybind11 to create a Python API around C/C++ binary dependencies.
+
+
+
+This is primarily intended to be used with hatchling and meson to build
+
+This tool parses C/C++ headers 
+
+
+It is especially designed to meet the needs of RobotPy's various wrapper
+libraries, chiefly around:
 
 * Managing upstream binary dependencies
 * Autogenerating pybind11 wrappers around those dependencies

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

@@ -72,3 +72,4 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
+

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 ``wrapcfg`` 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 `wrapcfg/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-gen --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
+``wrapcfg`` subdir, add files to ``NAME_sources``.
+
+.. code-block:: meson
+
+   subdir('wrapcfg')
+
+   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,38 +1,28 @@
 
 .. _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
+pyproject.toml
+==============
 
-   #!/usr/bin/env python3
-   from robotpy_build.setup import setup
-   setup()
+semiwrap is 
 
 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
+tell pip to install semiwrap (and any other dependencies) before starting
 a build.
 
 .. code-block:: toml
 
    [build-system]
    requires = ["robotpy-build>=2020.1.0,<2021.0.0"]
 
-Projects must include robotpy-build specific sections in their pyproject.toml.
-robotpy-build takes ``pyproject.toml`` and converts it to a python dictionary
+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 given to pydantic, which
 validates the structure of the dictionary against the objects described below.
 
@@ -49,73 +39,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