added C docs, new _Py module

MatrixEditor · Sep 7, 2024 · 8b63803 · 8b63803
1 parent 45c0a82
commit 8b63803
Show file tree

Hide file tree

Showing 51 changed files with 1,081 additions and 518 deletions.
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -68,8  68,9 @@
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
 html_theme_options = {
     "show_nav_level": 4,
     "navbar_end": ["navbar-icon-links", "theme-switcher"],
-    "collapse_navigation": True,
     "collapse_navigation": False,
     "github_url": "https://github.com/MatrixEditor/caterpillar",
     "logo": {
         "text": f"Caterpillar {version}",

diff --git a/docs/sphinx/source/extensions/c_annotations.py b/docs/sphinx/source/extensions/c_annotations.py
@@ -70,7  70,7 @@ def add_annotations(self, app, doctree):
                 rc = sphinx_gettext("Return value: New reference.")
             else:
                 rc = sphinx_gettext("Return value: Borrowed reference.")
-            node.insert(0, nodes.emphasis(rc, rc, classes=["refcount"]))
             node.insert(0, nodes.emphasis(rc, rc, classes=["refcount", "text-info"]))
 
 
 def init_annotations(app):

diff --git a/docs/sphinx/source/extensions/refcounts.dat b/docs/sphinx/source/extensions/refcounts.dat
@@ -7,5  7,36 @@ CpAtom_CallSize:PyObject*: 1
 CpStruct_New:PyObject*: 1
 CpStructModel_GetStruct:PyObject*: 1
 CpStruct_GetAnnotations:PyObject*: 1
 CpStructFieldInfo_New:CpStructFieldInfoObject*: 1
 
-CpCharAtom_Unpack:PyObject*: 1
 CpCharAtom_Unpack:PyObject*: 1
 
 CpContext_GetAttr:PyObject*: 1
 CpContext_GetAttrString:PyObject*: 1
 CpContext_New:CpContextObject*: 1
 
 CpUnaryExpr_New:CpUnaryExprObject*: 1
 CpBinaryExpr_New:CpBinaryExprObject*: 1
 
 CpField_New:CpFieldObject*: 1
 CpField_EvalSwitch:PyObject*: 1
 CpField_GetLength:PyObject*: 1
 
 CpContextPath_FromString:CpContextPathObject*: 1
 CpContextPath_New:CpContextPathObject*: 1
 
 CpObject_Create:PyObject*: 1
 CpObject_CreateOneArgs:PyObject*: 1
 CpObject_CreateNoArgs:PyObject*: 1
 
 CpTypeOf:PyObject*: 1
 CpSizeOf:PyObject*: 1
 
 CpState_New:CpStateObject*: 1
 CpState_Tell:PyObject*: 1
 CpState_Seek:PyObject*: 1
 CpState_Read:PyObject*: 1
 CpState_ReadFully:PyObject*: 1
 CpState_Write:PyObject*: 1
 
 CpLayer_New:CpLayerObject*: 1
diff --git a/docs/sphinx/source/reference/capi/arch.rst b/docs/sphinx/source/reference/capi/arch.rst
diff --git a/docs/sphinx/source/reference/capi/context.rst b/docs/sphinx/source/reference/capi/context.rst
@@ -12,12  12,13 @@ data. This procotol is implemented by *all* context-related classes in
 this package.
 
 
-.. py:function:: object.__context_getattr__(self, path) -> object
 .. py:method:: object.__context_getattr__(self, path) -> object
     :noindex:
 
     This function is used to retrieve a value from the context. It is implementation
     dependent whether nested paths are supported. By default, multiple path elements
     are sperated by a single dot.
 
     For example, consider the following path: :code:`"foo.bar"`. The context
     implementation should first resolve the value of :code:`"foo"` and then
-    retrieve the value of :code:`"bar"` from the result.
     retrieve the value of :code:`"bar"` from the result.
diff --git a/docs/sphinx/source/reference/capi/index.rst b/docs/sphinx/source/reference/capi/index.rst
diff --git a/docs/sphinx/source/reference/capi/macros.rst b/docs/sphinx/source/reference/capi/macros.rst
@@ -0,0  1,27 @@
 .. _reference-capi_macros:
 
 Defined Macros
 ==============
 
 
 
 .. c:macro:: _Cp_Name(name)
 
     Appends the name of the C module to the given name. For example, if the given
     name is :code:`"foo"`, the returned name is :code:`"caterpillar._C.foo"`.
 
 
 .. c:function:: PyObject *CpObject_Create(PyObject *type, const char *format, ...)
 
     Creates an object of the given type using the given arguments and returns it.
     Returns *NULL* if an error occurs.
 
 .. c:function:: PyObject *CpObject_CreateOneArgs(PyObject *type, PyObject *arg)
 
     Creates an object of the given type using the given argument and returns it.
     Returns *NULL* if an error occurs.
 
 .. c:function:: PyObject *CpObject_CreateNoArgs(PyObject *type)
 
     Creates an object of the given type and returns it. Returns *NULL* if an error occurs.
 
diff --git a/docs/sphinx/source/reference/capi/module.rst b/docs/sphinx/source/reference/capi/module.rst
@@ -0,0  1,96 @@
 .. _reference-capi_module:
 
 **********
 Module API
 **********
 
 
 .. c:var:: PyModuleDef CpModule;
 
     Global module object for the Caterpillar C module.
 
 
 .. c:function:: inline _modulestate *get_module_state(PyObject *module)
 
     Returns the :c:type:`_modulestate` for the given module.
 
 
 .. c:function:: inline _modulestate *get_global_module_state(void)
 
     Returns the :c:type:`_modulestate` using the global caterpillar module object.
 
 
 .. c:struct:: _modulestate
 
     The internal state for this module. It will store all necessary information
     about the core module.
 
     Global options:
 
     .. c:member:: PyObject* cp_option__dynamic;
                   PyObject* cp_option__sequential;
                   PyObject* cp_option__keep_position;
                   PyObject* cp_option__union;
                   PyObject* cp_option__eval;
                   PyObject* cp_option__discard_unnamed;
                   PyObject* cp_option__discard_const;
                   PyObject* cp_option__replace_types;
                   PyObject* cp_option__slots;
 
     Global default options:
 
     .. c:member:: PyObject* cp_option__global_field_options;
                   PyObject* cp_option__global_struct_options;
 
     Global arch and endian:
 
     .. c:member:: PyObject* cp_arch__host;
                   PyObject* cp_endian__native;
                   PyObject* cp_endian__big;
                   PyObject* cp_endian__little;
 
     Typing constants:
 
     .. c:member:: PyObject* Any_Type;
                   PyObject* List_Type;
                   PyObject* Union_Type;
                   PyObject* BytesIO_Type;
 
     String constants:
 
     .. c:member:: PyObject* str_path_delim = ".";
                   PyObject* str_tell = "tell";
                   PyObject* str_seek = "seek";
                   PyObject* str_write = "write";
                   PyObject* str_read = "read";
                   PyObject* str_close = "close";
                   PyObject* str_strict = "strict";
                   PyObject* str___pack__ = "__pack__";
                   PyObject* str___pack_many__ = "__pack_many__";
                   PyObject* str___unpack__ = "__unpack__";
                   PyObject* str___unpack_many__ = "__unpack_many__";
                   PyObject* str___size__ = "__size__";
                   PyObject* str___type__ = "__type__";
                   PyObject* str___annotations__ = "__annotations__";
                   PyObject* str___mro__ = "__mro__";
                   PyObject* str___struct__ = "__struct__";
                   PyObject* str___slots__ = "__slots__";
                   PyObject* str___match_args__ = "__match_args__";
                   PyObject* str___weakref__ = "__weakref__";
                   PyObject* str___dict__ = "__dict__";
                   PyObject* str___qualname__ = "__qualname__";
                   PyObject* str_start = "start";
                   PyObject* str_ctx__root = "<root>";
                   PyObject* str_ctx__getattr = "__context_getattr__";
                   PyObject* str_bytesio_getvalue = "getvalue";
                   PyObject* str_builder_process = "process";
                   PyObject* str_pattern_match = "match";
 
 .. c:macro:: CpModule_SetupType(op)
 
     Sets up the type object for the given module object. Expands to:
 
     .. code-block:: c
 
         if (PyType_Ready(op) < 0)
             return NULL;
diff --git a/docs/sphinx/source/reference/capi/objects/arch.rst b/docs/sphinx/source/reference/capi/objects/arch.rst
@@ -0,0  1,53 @@
 .. _capi_arch:
 
 Arch & Endian Objects
 =====================
 
 Arch Objects
 ------------
 
 .. c:var:: PyTypeObject CpArch_Type
 
     The type object for the :c:type:`CpArchObject` class.
 
 
 .. c:type:: CpArchObject
 
     *TODO*
 
 
 .. c:function:: int CpArch_CheckExact(PyObject *op)
 
     Checks if the given object is an :c:type:`CpArchObject`.
 
 
 .. c:function:: int CpArch_Check(PyObject *op)
 
     Checks if the given object is instance of an :c:type:`CpArchObject`.
 
 
 Endian Objects
 --------------
 
 .. c:var:: PyTypeObject CpEndian_Type
 
     The type object for the :c:type:`CpEndianObject` class.
 
 
 .. c:type:: CpEndianObject
 
     *TODO*
 
 .. c:function:: int CpEndian_IsLittleEndian(CpEndianObject *endian, _modulestate *mod)
 
     Returns ``1`` if the current system is little-endian and ``0`` otherwise.
 
 
 .. c:function:: int CpEndian_CheckExact(PyObject *op)
 
     Checks if the given object is an :c:type:`CpEndianObject`.
 
 
 .. c:function:: int CpEndian_Check(PyObject *op)
 
     Checks if the given object is instance of an :c:type:`CpEndianObject`
diff --git a/.../source/reference/capi/atoms/boolatom.rst → ...reference/capi/objects/atoms/boolatom.rst b/.../source/reference/capi/atoms/boolatom.rst → ...reference/capi/objects/atoms/boolatom.rst
diff --git a/.../source/reference/capi/atoms/charatom.rst → ...reference/capi/objects/atoms/charatom.rst b/.../source/reference/capi/atoms/charatom.rst → ...reference/capi/objects/atoms/charatom.rst