Convert "README.rst" to "README.md"

README.md

@@ -0,0 +1,100 @@
+
+# Briefcase Windows App Template
+
+A
+[Cookiecutter](https://github.com/cookiecutter/cookiecutter/)
+template for building Python apps that will run under Windows, packaged
+as an MSI installer.
+
+## Using this template
+
+The easiest way to use this project is to not use it at all - at least, not
+directly.
+[Briefcase](https://github.com/beeware/briefcase/)
+is a tool that uses this template, rolling it out using data extracted from a
+`pyproject.toml` configuration file.
+
+However, if you *do* want use this template directly...
+
+1. Install [cookiecutter](https://github.com/cookiecutter/cookiecutter).
+   This is a tool used to bootstrap complex project templates:
+
+    ```text
+    pip install cookiecutter
+    ```
+
+2. Run `cookiecutter` on the template:
+
+    ```text
+    cookiecutter https://github.com/beeware/briefcase-windows-app-template
+    ```
+
+   This will ask you for a number of details of your application, including the
+   name of your application (which should be a valid PyPI identifier), and
+   the Formal Name of your application (the full name you use to describe
+   your app). The remainder of these instructions will assume a name of
+   `my-project`, and a formal name of `My Project`.
+
+3. [Obtain a Python Windows Embeddable package](https://github.com/beeware/briefcase-windows-app-template#id1), and extract it into the
+   `My Project/src` directory generated by the template. This will give you a
+   `python3.dll` (amongst other artefacts) in the `My Project/src` folder.
+
+4. Add your code to the template, into the `My Project/src/app` directory.
+   At the very minimum, you need to have an `app/<app name>/__main__.py` file
+   that defines an entry point that will start your application.
+
+   If your code has any dependencies, they should be installed under the
+   `My Project/src/app_packages` directory.
+
+If you've done this correctly, a project with a formal name of `My Project`,
+with an app name of `my-project` should have a directory structure that
+looks something like:
+
+```text
+My Project/
+    src/
+        app/
+            my_project/
+                __init__.py
+                __main__.py
+                app.py
+        app_packages/
+            ...
+    python3.dll
+    ...
+    briefcase.toml
+    my-project.ico
+    my-project.wxs
+    MyProject.exe
+```
+
+This project can now be compiled with
+[WiX](https://wixtoolset.org)
+to produce an MSI file. Open a command prompt, and change into the `My Project`
+directory. Then:
+
+```text
+C:\...>wix build -ext WixToolset.UI.wixext -arch x64 my-project.wxs -loc unicode.wxl -o "My Project.msi"
+```
+
+The MSI file can then be used to install your application. When installed, your
+application will have an entry in your Start menu.
+
+## Next steps
+
+Of course, running Python code isn't very interesting by itself - you won't
+be able to do any console input or output, because a Windows app doesn't
+display a console.
+
+To do something interesting, you'll need to work with the native Windows system
+libraries to draw widgets and respond to screen taps. The
+[Python for .NET](https://pythonnet.github.io/)
+bridging library can be used to interface with the Windows system libraries.
+Alternatively, you could use a cross-platform widget toolkit that supports
+Windows (such as [Toga](https://beeware.org/project/toga/)) to provide a GUI
+for your application.
+
+If you have any external library dependencies (like Toga, or anything other
+third-party library), you should install the library code into the
+`app_packages` directory. This directory is the same as a  `site_packages`
+directory on a desktop Python install.