natConnect now returns a context manager. (#156)

documentation/index.rst

@@ -16,6 +16,7 @@ Unimacro is not yet working, a beta release for this state will be released pret
    :maxdepth: 2
    :caption: Contents:
 
+   overview
    install
    configure
    modules

documentation/overview.rst

@@ -0,0 +1,76 @@
+Introduction
+============
+Natlink has been used to extend Dragon Naturally Speaking (Dragon) with Python modules. Many developers of extensions 
+for Dragon find it more practical to develop and share extensions using Python than the built in Visual Basic macros of Dragon.
+
+Similarly, many end users find it easier to  use Dragon extensions written in Natlink than to locate and install 
+scripts using the built in Dragon scripting. However, an end user may have to edit or rename the occasional text file,
+or run a command lind program `pip` to install a Python package.
+
+End users interact with an extension with a Natlink grammar.  A grammar specifies what will 
+happen when certain words are dictated with grammar rules. 
+
+For example, a hypothetical grammar could have a very simple rule "american date today" which prints the current
+date out in a format mm/dd/yyyy.
+
+Grammars can be used to insert text boilerplate, operate the menus of programs, or otherwise control a computer.  
+They can even be used to help write computer programs.
+
+Using a Published Grammar
+=========================
+
+
+Installing a Published Grammar
+==============================
+
+Follow the instructions for the specific grammar or extension. If the author has published 
+the package xyz to PyPI  https://pypi.org/  you will be able to install it with a command line 'pip install xyz'
+in a command shell or powershell prompt and add the necessary lines to natlink.ini
+(something like xyz=xyz).  
+
+They might provide other instructions on installing the package with pip,
+or just provide a python file for you to figure out what to deal with. In the case where they just provide you python files, 
+the python files module must be placed in a folder listed in the directories section of natlink.ini. 
+
+
+
+As an end user of Natlink, you may be never need to write your own grammar, and you won't need programming skills.  
+You will need to Python packages and  grammars and perhaps do some small amount of configuration on your computer. 
+
+Grammars are implemented as Python modules. A Python module is a single Python 
+file which is identified with the ".py"
+extension.  Natlink needs to know to load these Python modules.  This is done through 
+the 
+TODO insert hyperlink   configuration file natlink.ini.
+
+natlink.ini has a [directories] setting that lists the directories (file folders) natlink loads grammars from.  
+You can add as many as you need.
+
+A line may look like
+`name = directory`
+
+The name on the left of the equals is just a one word descriptor, and natlink doesn't do much with the name. 
+Sometimes confusingly they may the same or similar
+as the directory on the right of the equals. 
+
+The directory can be:
+- the name of Python package you have installed.  Generally this is the easiest if someone has published a grammar 
+as a Python package.
+- a folder on your file system where you have placed the Python file OR 
+where an extension will place Python files.  
+
+In any case, natlink will load all the python code in all the directories listed in the natlink.ini config file.
+
+It can be confusing becuase you might see two directories with similar names.  For example,
+Vocola uses two directories in natlink.ini.  Natlink.ini will have two lines for Vocola:
+
+[directories]
+vocoladirectory = vocola2
+vocolagrammarsdirectory = natlink_userdir\vocolagrammars
+
+This is because vocola has a bunch of Python that needs to be loaded from the vocola2 Python package and
+a bunch more Python that vocola itself creates at runtime and places in vocolagrammarsdirectory.  Some other 
+natlink extensions do the same thing.  
+
+
+

pythonsrc/src/natlink/__init__.py

@@ -10,6 +10,7 @@
 import traceback
 import winreg
 import ctypes
+import contextlib
 W32OutputDebugString = ctypes.windll.kernel32.OutputDebugStringW
 
 #copied from pydebugstring.  
@@ -83,3 +84,20 @@ def execScript(script,args=None):
 
 def toWindowsEncoding(str_to_encode):
     return str_to_encode.encode('Windows-1252')
+
+#wrap the C++ natConnect with a version that returns a context manager
+
+_original_natconnect=natConnect
+def wrappedNatConnect(*args,**keywords):
+    _original_natconnect(*args,**keywords)
+    return NatlinkConnector()
+natConnect=wrappedNatConnect
+
+@contextlib.contextmanager
+def NatlinkConnector():
+    """context manager for natlink connections.
+    """
+    # use the method from https://towardsdatascience.com/how-to-build-custom-context-managers-in-python-31727ffe96e1
+    yield
+    print("natlink disconnecting")
+    natDisconnect()

pythonsrc/tests/manual_test_dragoncode.py

@@ -32,10 +32,10 @@ def natlink_connection(monkeymodule):
     monkeymodule.setenv("natlink_userdir",str(mock_folder))
 
     print("\nConnecting natlink")
-    yield n.natConnect()  #will be none
-    print("\nDisconnecting natlink")
-    n.natDisconnect()
+    with n.natConnect():
+        yield n.natConnect()   
 
+
 @pytest.fixture(scope="module")
 def mock_userdir(monkeypatch):
     mock_folder=p.WindowsPath(os.path.dirname(__file__)) / "mock_userdir"

readme.md

@@ -6,6 +6,13 @@ Documentation available at [natlink.reddthedocs.io](https://natlink.readthedocs.
 
 The documention is not yet complete at [natlink.reddthedocs.io](https://natlink.readthedocs.io/en/latest/).  The remainder of this document contains information that  has not yet been introduced into [natlink.readthedocs.io](https://natlink.readthedocs.io/en/latest/):
 
+## Editing Documentation
+The documentation is in the documentation folder.  In that folder you can type
+`pip install -r requirements.txt` which will bring in the tools that build the documentation 
+from text files in that folder.
+
+`make.bat html` will build the documentation.
+
 # Section: \[directories\]