Add initial documentation setup

pythonnet · filmor · Sep 26, 2022 · May 26, 2022 · Sep 19, 2022 · Sep 26, 2022
commit 08fd638119b97e60f154f11fc1f103077bcd03ed
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,40 @@
+name: Documentation
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Doxygen Action
+      uses: mattnotmitt/[email protected]
+      with:
+        working-directory: "doc/"
+
+    - name: Build Sphinx documentation
+      run: |
+        pip install -r doc/requirements.txt
+        sphinx-build doc/source/ ./doc/build/html/
+
+    - name: Upload artifact
+      # Automatically uploads an artifact from the './_site' directory by default
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: doc/build/html/
+
+  deploy:
+    if: github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1,2 @@
+doxygen_xml/
+build/
diff --git a/doc/Doxyfile b/doc/Doxyfile
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/make.bat b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -0,0 +1,12 @@
+sphinx
+
+# Theme, force pygments update
+furo>=2022.9.15
+pygments>=2.7
+
+# Markdown
+myst-parser
+
+# C# via doxygen
+breathe
+git+https://github.com/rogerbarton/sphinx-csharp.git
diff --git a/doc/source/_static/.keep b/doc/source/_static/.keep
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Python.NET'
+copyright = '2022, The Python.NET Project Contributors'
+author = 'The Python.NET Project Contributors'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser',
+    'breathe',
+    'sphinx.ext.autodoc',
+    'sphinx_csharp',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'furo'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+breathe_projects = { "pythonnet": "../doxygen_xml" }
+breathe_default_project = 'pythonnet'
diff --git a/doc/source/dotnet.md b/doc/source/dotnet.md
@@ -0,0 +1,136 @@
+# Embedding Python into .NET
+
+**Note:** because Python code running under Python.NET is inherently
+unverifiable, it runs totally under the radar of the security infrastructure
+of the CLR so you should restrict use of the Python assembly to trusted code.
+
+The Python runtime assembly defines a number of public classes that
+provide a subset of the functionality provided by the Python C-API.
+
+These classes include PyObject, PyList, PyDict, PyTuple, etc.
+
+At a very high level, to embed Python in your application you will need to:
+
+-   Reference Python.Runtime.dll in your build environment
+-   Call PythonEngine.Initialize() to initialize Python
+-   Call PythonEngine.ImportModule(name) to import a module
+
+The module you import can either start working with your managed app
+environment at the time its imported, or you can explicitly lookup and
+call objects in a module you import.
+
+For general-purpose information on embedding Python in applications,
+use www.python.org or Google to find (C) examples. Because
+Python.NET is so closely integrated with the managed environment,
+you will generally be better off importing a module and deferring to
+Python code as early as possible rather than writing a lot of managed
+embedding code.
+
+**Important Note for embedders:** Python is not free-threaded and
+uses a global interpreter lock to allow multi-threaded applications
+to interact safely with the Python interpreter.
+Much more information about this is available in the Python C-API
+documentation on the www.python.org Website.
+
+When embedding Python in a managed application, you have to manage the
+GIL in just the same way you would when embedding Python in
+a C or C++ application.
+
+Before interacting with any of the objects or APIs provided by the
+Python.Runtime namespace, calling code must have acquired the Python
+global interpreter lock by calling the `PythonEngine.AcquireLock` method.
+The only exception to this rule is the `PythonEngine.Initialize` method,
+which may be called at startup without having acquired the GIL.
+
+When finished using Python APIs, managed code must call a corresponding
+`PythonEngine.ReleaseLock` to release the GIL and allow other threads
+to use Python.
+
+A `using` statement may be used to acquire and release the GIL:
+
+```csharp
+using (Py.GIL())
+{
+    PythonEngine.Exec("doStuff()");
+}
+```
+
+The AcquireLock and ReleaseLock methods are thin wrappers over the
+unmanaged `PyGILState_Ensure` and `PyGILState_Release` functions from
+the Python API, and the documentation for those APIs applies to
+the managed versions.
+
+## Passing C# Objects to the Python Engine
+
+This section demonstrates how to pass a C# object to the Python runtime.
+The example uses the following `Person` class:
+
+```csharp
+public class Person
+{
+    public Person(string firstName, string lastName)
+    {
+        FirstName = firstName;
+        LastName = lastName;
+    }
+
+    public string FirstName { get; set; }
+    public string LastName { get; set; }
+}
+```
+
+In order to pass a C# object to the Python runtime, it must be converted to a
+`PyObject`. This is done using the `ToPython()` extension method. The `PyObject`
+may then be set as a variable in a `PyScope`. Code executed from the scope
+will have access to the variable:
+
+```csharp
+// create a person object
+Person person = new Person("John", "Smith");
+
+// acquire the GIL before using the Python interpreter
+using (Py.GIL())
+{
+    // create a Python scope
+    using (PyScope scope = Py.CreateScope())
+    {
+        // convert the Person object to a PyObject
+        PyObject pyPerson = person.ToPython();
+
+        // create a Python variable "person"
+        scope.Set("person", pyPerson);
+
+        // the person object may now be used in Python
+        string code = "fullName = person.FirstName + ' ' + person.LastName";
+        scope.Exec(code);
+    }
+}
+```
+
+[1]: http://www.ironpython.com
+
+[2]: http://pythonnet.github.io/
+
+[3]: https://mail.python.org/mailman3/lists/pythonnet.python.org/
+
+[4]: https://mail.python.org/archives/list/[email protected]/
+
+[5]: https://github.com/pythonnet/pythonnet/releases
+
+[6]: https://pypi.python.org/pypi/pythonnet
+
+[7]: http://www.go-mono.com
+
+[8]: https://github.com/pythonnet/pythonnet/blob/master/README.rst#embedding-python-in-net
+
+[9]: http://pythonnet.github.io/LICENSE
+
+[10]: http://www.python.org/license.html
+
+[55]: http://github.com/pythonnet/pythonnet/issues
+
+[77]: http://github.com/pythonnet/pythonnet
+
+[78]: https://github.com/pythonnet/pythonnet/wiki/Installation
+
+[79]: https://github.com/pythonnet/pythonnet/wiki
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -0,0 +1,66 @@
+.. Python.NET documentation master file, created by
+   sphinx-quickstart on Thu May 26 12:32:51 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Python.NET's documentation!
+======================================
+
+Python.NET (`pythonnet`) is a package that gives Python programmers nearly
+seamless integration with the .NET 4.0+ Common Language Runtime (CLR) on Windows
+and Mono runtime on Linux and OSX. Python.NET provides a powerful application
+scripting tool for .NET developers. Using this package you can script .NET
+applications or build entire applications in Python, using .NET services and
+components written in any language that targets the CLR (C#, VB.NET, F#,
+C++/CLI).
+
+Note that this package does _not_ implement Python as a first-class CLR
+language - it does not produce managed code (IL) from Python code. Rather,
+it is an integration of the CPython engine with the .NET or Mono runtime.
+This approach allows you to use CLR services and continue to use existing
+Python code and C-API extensions while maintaining native execution
+speeds for Python code. If you are interested in a pure managed-code
+implementation of the Python language, you should check out the
+`IronPython`_ project.
+
+Python.NET is currently compatible and tested with Python releases from 3.7
+onwards.
+
+Current releases are available on `PyPi <https://pypi.org/project/pythonnet/>`_
+and `Nuget.org <https://nuget.org/packages/pythonnet>`_.
+
+To subscribe to the `Python.NET mailing list <ml_>`_ or read the
+`online archives`_ of the list, see the `mailing list information <ml_>`_
+page. Use the `Python.NET issue tracker`_ to report issues.
+
+.. _IronPython: https://ironpython.net/
+.. _ml: https://mail.python.org/mailman3/lists/pythonnet.python.org/
+.. _online archives: https://mail.python.org/archives/list/[email protected]/
+.. _Python.NET issue tracker: https://github.com/pythonnet/pythonnet/issues
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    python
+    dotnet
+    reference
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+License
+=======
+
+Python.NET is released under the open source MIT License. A copy of the license
+is included in the distribution, or you can find a copy of the license
+online.
+
+.NET Foundation
+===============
+
+This project is supported by the `.NET Foundation <https://dotnetfoundation.org>`_.