From cb557b0fcd9a5a4a6d6c4af1abfe9be5ec057c69 Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Sat, 3 Aug 2024 10:17:39 +1000 Subject: [PATCH] Setup a documentation site --- .github/workflows/docs.yml | 50 +++++++++++++++++++++++++++++++ .gitignore | 3 +- README.md | 2 +- docs/examples.md | 2 ++ docs/getting-started.md | 42 ++++++++++++++++++++++++++ docs/index.md | 61 ++++++++++++++++++++++++++++++++++++++ docs/limitations.md | 14 +++++++++ docs/requirements.txt | 1 + mkdocs.yml | 6 ++++ 9 files changed, 179 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/examples.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/limitations.md create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..cf19ccd1 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 85f209c4..ad181728 100644 --- a/.gitignore +++ b/.gitignore @@ -485,4 +485,5 @@ $RECYCLE.BIN/ *.orig -.venv \ No newline at end of file +.venv +site/ \ No newline at end of file diff --git a/README.md b/README.md index e6a38ce7..fd1b1dbc 100644 --- a/README.md +++ b/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 diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 00000000..790d498a --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,2 @@ +# Example Solutions + diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..d666b48e --- /dev/null +++ b/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 + + + Always + +``` + +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 + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..ec4808bb --- /dev/null +++ b/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) + +drawing + +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` | +| `dict[K, V]` | `IReadOnlyDictionary` | +| `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. diff --git a/docs/limitations.md b/docs/limitations.md new file mode 100644 index 00000000..cf41782a --- /dev/null +++ b/docs/limitations.md @@ -0,0 +1,14 @@ +# Limitations + +## Type Hinting + + +### Variadic Generics + +C# does not have a notion of `Tuple`, 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. \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..b854bca2 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..27f09643 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,6 @@ +site_name: CSnakes +nav: + - Home: index.md + - Getting Started: getting-started.md + - Limitations: limitations.md + - Examples: examples.md \ No newline at end of file