Merge pull request #221 from tonybaloney/docs_updates

Docs updates for release

README.md

@@ -5,23 +5,24 @@
 
 [Documentation](https://tonybaloney.github.io/CSnakes/)
 
-[![NuGet Version](https://img.shields.io/nuget/v/CSnakes?label=CSnakes)](https://www.nuget.org/packages/CSnakes)
 [![NuGet Version](https://img.shields.io/nuget/v/CSnakes.Runtime?label=CSnakes.Runtime)](https://www.nuget.org/packages/CSnakes.Runtime)
 
 <img src="docs/res/logo.jpeg" alt="drawing" width="200"/> 
 
 CSnakes is a .NET Source Generator and Runtime that you can use to embed Python code and libraries into your .NET Solution without the need for REST, HTTP, or Microservices.
 
-![image](https://github.com/tonybaloney/PythonCodeGen/assets/1532417/39ca2f2a-416b-447a-a237-59e9613a4990)
+![image](https://github.com/tonybaloney/CSnakes/assets/1532417/39ca2f2a-416b-447a-a237-59e9613a4990)
 
 ## Features
 
-- .NET Standard 2.0 (.NET 6-8)
+- Supports .NET Standard 8-9
 - Supports Python 3.9-3.13
-- Supports Virtual Environments and C-Extensions
+- [Supports Virtual Environments and C-Extensions](https://tonybaloney.github.io/CSnakes/getting-started/#using-virtual-environments)
 - Supports Windows, macOS, and Linux
+- [Tight integration between NumPy ndarrays and Spans, 2D Spans and TensorSpans (.NET 9)](https://tonybaloney.github.io/CSnakes/buffers/)
 - Uses Python's C-API for fast invocation of Python code directly in the .NET process
 - Uses Python type hinting to generate function signatures with .NET native types
+- Supports CPython 3.13 "free-threading" mode
 - Supports nested sequence and mapping types (`tuple`, `dict`, `list`)
 - Supports default values
 

docs/advanced.md

@@ -126,3 +126,13 @@ public sealed class ExampleDirectIntegration : IDisposable
     }
 }
 ```
+
+### Disabling the Source Generator
+
+The Source Generator will only activate on files that are marked as `AdditionalFiles` in the project file. If you want to disable the Source Generator, you can remove the `AdditionalFiles` entry from the project file.
+
+Alternatively , you can disable the Source Generator by setting the `DisableCSnakesRuntimeSourceGenerator` property in the project file:
+
+```xml
+<DisableCSnakesRuntimeSourceGenerator>true</DisableCSnakesRuntimeSourceGenerator>
+```

docs/buffers.md

@@ -33,8 +33,7 @@ var bufferObject = testModule.ExampleArray();
 
 // check if the buffer is scalar (single dimensional)
 if (bufferObject.IsScalar) {
-
-// Get the buffer contents as a Span of bool
+    // Get the buffer contents as a Span of bool
 	Span<bool> result = bufferObject.AsBoolSpan();
 	Console.WriteLine(result[0]); // True
 	Console.WriteLine(result[4]); // False
@@ -110,22 +109,24 @@ Console.WriteLine(resultTensor[1, 2, 3, 4]); // 3
 
 The Numpy dtypes are mapped to C# types as follows:
 
-| NumPy dtype | C# Type | Span Method | ReadOnly Span Method | Span2D Method | ReadOnly Span2D Method |
-|-------------|---------|-------------|----------------------|---------------|------------------------|
-| `bool`      | `bool`  | `AsBoolSpan`| `AsBoolReadOnlySpan` | `AsBoolSpan2D`| `AsBoolReadOnlySpan2D` |
-| `int8`      | `sbyte` | `AsSByteSpan`| `AsSByteReadOnlySpan` | `AsSByteSpan2D`| `AsSByteReadOnlySpan2D` |
-| `int16`     | `short` | `AsShortSpan`| `AsShortReadOnlySpan` | `AsShortSpan2D`| `AsShortReadOnlySpan2D` |
-| `int32`     | `int`   | `AsIntSpan`  | `AsIntReadOnlySpan`   | `AsIntSpan2D`  | `AsIntReadOnlySpan2D`   |
-| `int64`     | `long`  | `AsLongSpan` | `AsLongReadOnlySpan`  | `AsLongSpan2D` | `AsLongReadOnlySpan2D`  |
-| `uint8`     | `byte`  | `AsByteSpan` | `AsByteReadOnlySpan`  | `AsByteSpan2D` | `AsByteReadOnlySpan2D`  |
-| `uint16`    | `ushort`| `AsUShortSpan`| `AsUShortReadOnlySpan`| `AsUShortSpan2D`| `AsUShortReadOnlySpan2D`|
-| `uint32`    | `uint`  | `AsUIntSpan` | `AsUIntReadOnlySpan`  | `AsUIntSpan2D` | `AsUIntReadOnlySpan2D`  |
-| `uint64`    | `ulong` | `AsULongSpan`| `AsULongReadOnlySpan` | `AsULongSpan2D`| `AsULongReadOnlySpan2D` |
-| `float32`   | `float` | `AsFloatSpan`| `AsFloatReadOnlySpan` | `AsFloatSpan2D`| `AsFloatReadOnlySpan2D` |
-| `float64`   | `double`| `AsDoubleSpan`| `AsDoubleReadOnlySpan`| `AsDoubleSpan2D`| `AsDoubleReadOnlySpan2D`|
+| NumPy dtype | C# Type  | Span Method    | ReadOnly Span Method   | Span2D Method    | ReadOnly Span2D Method   | TensorSpan Method    | ReadOnly TensorSpan Method   |
+|-------------|----------|----------------|------------------------|------------------|--------------------------|----------------------|------------------------------|
+| `bool`      | `bool`   | `AsBoolSpan`   | `AsBoolReadOnlySpan`   | `AsBoolSpan2D`   | `AsBoolReadOnlySpan2D`   | `AsBoolTensorSpan`   | `AsBoolReadOnlyTensorSpan`   |
+| `int8`      | `sbyte`  | `AsSByteSpan`  | `AsSByteReadOnlySpan`  | `AsSByteSpan2D`  | `AsSByteReadOnlySpan2D`  | `AsSByteTensorSpan`  | `AsSByteReadOnlyTensorSpan`  |
+| `int16`     | `short`  | `AsInt16Span`  | `AsInt16ReadOnlySpan`  | `AsInt16Span2D`  | `AsInt16ReadOnlySpan2D`  | `AsInt16TensorSpan`  | `AsInt16ReadOnlyTensorSpan`  |
+| `int32`     | `int`    | `AsInt32pan`   | `AsInt32ReadOnlySpan`  | `AsInt32pan2D`   | `AsInt32ReadOnlySpan2D`  | `AsInt32TensorSpan`  | `AsInt32ReadOnlyTensorSpan`  |
+| `int64`     | `long`   | `AsInt64Span`  | `AsInt64ReadOnlySpan`  | `AsInt64Span2D`  | `AsInt64ReadOnlySpan2D`  | `AsInt64TensorSpan`  | `AsInt64ReadOnlyTensorSpan`  |
+| `uint8`     | `byte`   | `AsByteSpan`   | `AsByteReadOnlySpan`   | `AsByteSpan2D`   | `AsByteReadOnlySpan2D`   | `AsByteTensorSpan`   | `AsByteReadOnlyTensorSpan`   |
+| `uint16`    | `ushort` | `AsUInt16Span` | `AsUInt16ReadOnlySpan` | `AsUInt16Span2D` | `AsUInt16ReadOnlySpan2D` | `AsUInt16TensorSpan` | `AsUInt16ReadOnlyTensorSpan` |
+| `uint32`    | `uint`   | `AsUInt32Span` | `AsUInt32ReadOnlySpan` | `AsUInt32Span2D` | `AsUInt32ReadOnlySpan2D` | `AsUInt32TensorSpan` | `AsUInt32ReadOnlyTensorSpan` |
+| `uint64`    | `ulong`  | `AsUInt64Span` | `AsUInt64ReadOnlySpan` | `AsUInt64Span2D` | `AsUInt64ReadOnlySpan2D` | `AsUInt64TensorSpan` | `AsUInt64ReadOnlyTensorSpan` |
+| `float32`   | `float`  | `AsFloatSpan`  | `AsFloatReadOnlySpan`  | `AsFloatSpan2D`  | `AsFloatReadOnlySpan2D`  | `AsFloatTensorSpan`  | `AsFloatReadOnlyTensorSpan`  |
+| `float64`   | `double` | `AsDoubleSpan` | `AsDoubleReadOnlySpan` | `AsDoubleSpan2D` | `AsDoubleReadOnlySpan2D` | `AsDoubleTensorSpan` | `AsDoubleReadOnlyTensorSpan` |
 
 The `GetItemType()` method can be used to get the C# type of the buffer contents. 
 
+You can also use generic methods such as `AsSpan<T>` and `AsReadOnlySpan<T>` to get a Span of the buffer contents with the specified type. If the requested type does not match the buffer contents, an exception will be thrown.
+
 ## Bytes objects as buffers
 
 In addition to NumPy arrays, you can also use `bytes` and `bytearray` objects as buffers. The `Buffer` type hint can be used to indicate that a function returns a `bytes` or `bytearray` object that supports the Buffer Protocol.

docs/getting-started.md

@@ -5,7 +5,7 @@ To get started with CSnakes, you need to:
 * [Install Python](#installing-python)
 * [Put your Python files into a C# Project](#configuring-a-c-project-for-csnakes)
 * [Use type annotations for the functions you want to call from C#](#using-type-annotations-for-reflection)
-* [Install the `CSnakes` and `CSnakes.Runtime` packages into the project](#installing-the-nuget-packages-for-csnakes)
+* [Install the `CSnakes.Runtime` package into the project](#installing-the-nuget-packages-for-csnakes)
 * [Mark them for source generation](#marking-files-for-generation)
 * [Install the `CSnakes.Runtime` nuget package in the C# Project you want to execute the Python code from](#building-the-project)
 * [Setup a Virtual Environment (Optional)](#using-virtual-environments)
@@ -32,18 +32,15 @@ To setup a C# project for CSnakes, you need to:
 1. Create a new C# project or open an existing one.
 2. Add your Python files to the project.
 3. Mark the Python files as "Additional Files" in the project file.
-4. Install the `CSnakes` and `CSnakes.Runtime` NuGet packages.
+4. Install the `CSnakes.Runtime` NuGet package.
 5. Create a `PythonEnvironment` in C# and create an instance of the Python module.
 6. Call any Python code. 
 
-### Installing the NuGet packages
+### Installing the NuGet package
 
-CSnakes has two nuget packages that you need to install in your C# project:
+CSnakes is bundled into a single nuget package, [`CSnakes.Runtime`](https://www.nuget.org/packages/CSnakes.Runtime/). This package includes the source generator and runtime libraries.
 
-1. [`CSnakes`](https://www.nuget.org/packages/CSnakes/) - the source generator that will create the C# classes from your Python files. Install this in the project that contains the Python files.
-2. [`CSnakes.Runtime`](https://www.nuget.org/packages/CSnakes.Runtime/) - the runtime that will execute the Python code. Install this in the project that will call the Python code.
-
-If you are using one project for both the Python code and the C# code, you can install both packages in the same project.
+Source Generation is recommended for the best experience, but you can also use the runtime library directly if you prefer, see [Calling Python without the Source Generator](advanced.md#calling-python-without-the-source-generator).
 
 ## Adding Python files
 
@@ -67,6 +64,7 @@ For CSnakes to run the source generator over Python files, you need to mark the
         <AdditionalFiles Include="demo.py">
             <CopyToOutputDirectory>Always</CopyToOutputDirectory>
         </AdditionalFiles>
+    </ItemGroup>
 ```
 
 Or, in Visual Studio change the properties of the file and set **Build Action** to **Csharp analyzer additional file**.

docs/index.md

@@ -1,6 +1,5 @@
 # CSnakes - a tool for embedding Python code into .NET projects
 
-[![NuGet Version](https://img.shields.io/nuget/v/CSnakes?label=CSnakes)](https://www.nuget.org/packages/CSnakes)
 [![NuGet Version](https://img.shields.io/nuget/v/CSnakes.Runtime?label=CSnakes.Runtime)](https://www.nuget.org/packages/CSnakes.Runtime)
 
 ![logo](res/logo.jpeg){ align=left width=30% }
@@ -15,20 +14,22 @@ Check out the [getting started](getting-started.md) guide or check out the [demo
 
 ## Features
 
-- .NET Standard 2.0 (.NET 6+)
+- Supports .NET 8 and 9
 - Supports Python 3.9-3.13
-- Supports Virtual Environments and C-Extensions
+- [Supports Virtual Environments and C-Extensions](getting-started.md#using-virtual-environments)
 - Supports Windows, macOS, and Linux
+- [Tight integration between NumPy ndarrays and Spans, 2D Spans and TensorSpans (.NET 9)](buffers.md)
 - Uses Python's C-API for fast invocation of Python code directly in the .NET process
 - Uses Python type hinting to generate function signatures with .NET native types
-- Supports nested sequence and mapping types (`tuple`, `dict`, `list`)
-- Supports default values
-- Efficiently access numpy arrays as 1 or 2 dimensional Spans [1](buffers.md)
+- Supports [CPython 3.13 "free-threading" mode](advanced.md#free-threading-mode)
+- Supports [nested sequence and mapping types (`tuple`, `dict`, `list`)](reference.md)
+- Supports [default values](reference.md#default-values)
+
 
 ## Benefits
 
 - Uses native Python type hinting standards to produce clean, readable C# code with minimal boiler plate!
-- Integration between .NET and Python is done at the C-API, meaning strong compatibility between Python versions 3.8-3.12 and .NET 6-8.
+- Integration between .NET and Python is done at the C-API, meaning strong compatibility between Python versions 3.8-3.13 and .NET 8-9.
 - Integration is low-level and high-performance.
 - CSnakes uses the CPython C-API and is compatible with all Python extensions.
 - Invocation of Python code and libraries is in the same process as .NET