Add documentation for the cstruct-stubgen tool (#87)

Author: Miauwkeru

docs/source/images/autocompletion.png

@@ -201,6 +201,90 @@ Custom definition parsers
 
 Don't like the C-like definition syntax? Write your own syntax parser!
 
+cstruct-stubgen
+---------------
+
+``cstruct-stubgen`` is a tool that generates Python stub files (``.pyi``) from ``dissect.cstruct`` definitions.
+These stubs provide an enhanced developer experience in your IDE, enabling type checking and code completion.
+
+The most basic usage of ``cstruct-stubgen`` is as simple as:
+
+.. code-block:: console
+
+   $ cstruct-stubgen /path/to/project/source/files
+
+So in the case of the following cstruct definition:
+
+.. code-block:: python
+
+   from dissect.cstruct import cstruct
+
+   c_systemtime_def = """
+   struct SYSTEMTIME {
+       WORD    wYear;
+       WORD    wMonth;
+       WORD    wDayOfWeek;
+       WORD    wDay;
+       WORD    wHour;
+       WORD    wMinute;
+       WORD    wSecond;
+       WORD    wMilliseconds;
+   };
+   """
+   c_systemtime = cstruct().load(c_systemtime_def)
+
+The generated ``.pyi`` file will look like:
+
+.. code-block:: python
+
+   # Generated by cstruct-stubgen
+   from typing import BinaryIO, Literal, overload
+
+   import dissect.cstruct as __cs__
+   from typing_extensions import TypeAlias
+
+   class _c_systemtime(__cs__.cstruct):
+       class SYSTEMTIME(__cs__.Structure):
+           wYear: _c_systemtime.uint16
+           wMonth: _c_systemtime.uint16
+           wDayOfWeek: _c_systemtime.uint16
+           wDay: _c_systemtime.uint16
+           wHour: _c_systemtime.uint16
+           wMinute: _c_systemtime.uint16
+           wSecond: _c_systemtime.uint16
+           wMilliseconds: _c_systemtime.uint16
+           @overload
+           def __init__(self, wYear: _c_systemtime.uint16 | None = ..., wMonth: _c_systemtime.uint16 | None = ..., wDayOfWeek: _c_systemtime.uint16 | None = ..., wDay: _c_systemtime.uint16 | None = ..., wHour: _c_systemtime.uint16 | None = ..., wMinute: _c_systemtime.uint16 | None = ..., wSecond: _c_systemtime.uint16 | None = ..., wMilliseconds: _c_systemtime.uint16 | None = ...): ...
+           @overload
+           def __init__(self, fh: bytes | memoryview | bytearray | BinaryIO, /): ...
+
+   # Technically `c_systemtime` is an instance of `_c_systemtime`, but then we can't use it in type hints
+   c_systemtime: TypeAlias = _c_systemtime
+
+And the autocompletion, with an IDE such as VS Code, will look like:
+
+.. image:: /images/autocompletion.png
+
+.. image:: /images/autocompletion_attribute.png
+
+Structure fields also have correct typing, enabling further type checking and code completion on compatible Python types:
+
+.. image:: /images/field_typing_struct.png
+
+.. image:: /images/field_typing_char.png
+
+.. note::
+
+    ``cstruct-stubgen`` generates type hints for cstruct definitions only.
+    Other definitions or functions in the ``.py`` file are not included.
+    To make them visible in your IDE, manually add the missing functions and variables to the ``.pyi`` file.
+
+.. sphinx_argparse_cli::
+   :module: dissect.cstruct.tools.stubgen
+   :func: main
+   :prog: cstruct-stubgen
+   :hook:
+
 Reference
 ---------