Setup a documentation site

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Deploy Mkdocs site
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Build HTML with mkdocs
+        run: |
+          python -m pip install -r docs/requirements.txt
+          python -m mkdocs build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -485,4 +485,5 @@ $RECYCLE.BIN/
 
 *.orig
 
-.venv
+.venv
+site/

README.md

@@ -17,7 +17,7 @@ CSnakes is a .NET Source Generator and Runtime that you can use to embed Python
 - 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`)
-- Suports default values
+- Supports default values
 
 ## Examples
 

docs/examples.md

@@ -0,0 +1,2 @@
+# Example Solutions
+

docs/getting-started.md

@@ -0,0 +1,42 @@
+# Getting Started
+
+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)
+* [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)
+* [Instantiate a Python environment in C# and run the Python function](#calling-csnakes-code-from-cnet)
+
+## Installing Python
+
+## Configuring a C# Project for CSnakes
+
+## Using type annotations for reflection
+
+## Installing the nuget packages for CSnakes
+
+## Marking files for generation
+
+You can either mark a file as an "Additional File" in the CSProj file XML:
+
+```xml
+    <ItemGroup>
+        <AdditionalFiles Include="hello_world.py">
+            <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+        </AdditionalFiles>
+```
+
+Or, in Visual Studio change the properties of the file and set **Build Action** to **Csharp analyzer additional file**.
+
+## Building the project
+
+## Using Virtual Environments
+
+Since most Python projects require external dependencies outside of the Python standard library, CSnakes supports execution within a Python virtual environment.
+
+## Calling CSnakes code from C#.NET
+

docs/index.md

@@ -0,0 +1,61 @@
+# CSnakes - a tool for embedding Python code into .NET projects
+
+[![NuGet Version](https://img.shields.io/nuget/v/CSnakes)](https://www.nuget.org/packages/CSnakes)
+
+<img src="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)
+
+## Features
+
+- .NET Standard 2.0 (.NET 6+)
+- Supports up to Python 3.12
+- Supports Virtual Environments and C-Extensions
+- Supports Windows, macOS, and Linux
+- 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
+
+## Example
+
+CSnakes will generate a C#.NET class for any Python file in a project that is tagged as CSharp Analyzer Additional File (see [Getting Started](getting-started.md)).
+All functions in that class with type annotations will be reflected to callable C# methods and an environment builder added to that module.
+
+## Supported Types
+
+CSnakes supports the following typed scenarios:
+
+| Python type annotation | Reflected C# Type |
+|------------------------|-------------------|
+| `int`                  | `long`            |
+| `float`                | `double`          |
+| `str`                  | `string`          |
+| `bool`                 | `bool`            |
+| `list[T]`              | `IEnumerable<T>`  |
+| `dict[K, V]`           | `IReadOnlyDictionary<K, V>` |
+| `tuple[T1, T2, ...]`   | `(T1, T2, ...)`   |
+
+### Return types
+
+The same type conversion applies for the return type of the Python function, with the additional feature that functions which explicitly return type `None` are declared as `void` in C#.
+
+### Default values
+
+CSnakes will use the default value for arguments of types `int`, `float`, `str`, and `bool` for the generated C# method. For example, the following Python code:
+
+```python
+def example(a: int = 123, b: bool = True, c: str = "hello", d: float = 1.23) -> None
+  ...
+
+```
+
+Will generate the following C#.NET method signature:
+
+```csharp
+public void Example(long a = 123, bool b = true, string c = "hello", double d = 1.23)
+```
+
+1. CSnakes will treat `=None` default values as nullable arguments. The Python runtime will set the value of the parameter to the `None` value at execution.

docs/limitations.md

@@ -0,0 +1,14 @@
+# Limitations
+
+## Type Hinting
+
+
+### Variadic Generics
+
+C# does not have a notion of `Tuple<T...>`, so the type annotation using `Tuple[*T]` in Python cannot be statically converted into a C#.NET type. See [PEP646](https://peps.python.org/pep-0646/) for more details.
+
+If you really want this feature, see issue [25](https://github.com/tonybaloney/CSnakes/issues/25).
+
+## Classes
+
+CSnakes does not support source generation for custom types, this includes dataclasses and named tuple instances. If you would really like this feature, please [raise an issue](https://github.com/tonybaloney/CSnakes/issues/new) and describe your use case.

docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs

mkdocs.yml

@@ -0,0 +1,6 @@
+site_name: CSnakes
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Limitations: limitations.md
+  - Examples: examples.md