Merge pull request #107 from elextr/geanypy

Adding Geanypy to geany-plugins

.gitignore

@@ -7,6 +7,7 @@
 *.so
 *.dll
 *.exe
+*.pyc
 deps.mak
 .deps/
 .libs/

MAINTAINERS

@@ -114,6 +114,12 @@ M: Yura Siamashka <yurand2@gmail.com>
 W: http://plugins.geany.org/geanyprj.html
 S: Odd Fixes
 
+geanypy
+P: Lex Trotman <elextr@gmail.com>
+M: Lex Trotman <elextr@gmail.com>
+W: http://plugins.geany.org/geanypy.html
+S: Maintained
+
 geanysendmail
 P: Frank Lanitz <frank@frank.uvena.de>
 M: Frank Lanitz <frank@frank.uvena.de>

Makefile.am

@@ -1,4 +1,4 @@
-ACLOCAL_AMFLAGS = -I build/cache -I build -I build/bundled --install
+ACLOCAL_AMFLAGS = -I build/cache -I build -I build/bundled -I geanypy/m4 --install
 
 SUBDIRS = po
 
@@ -70,6 +70,10 @@ if ENABLE_GEANYPRJ
 SUBDIRS += geanyprj
 endif
 
+if ENABLE_GEANYPY
+SUBDIRS += geanypy
+endif
+
 if ENABLE_GEANYSENDMAIL
 SUBDIRS += geanysendmail
 endif

build/geanypy.m4

@@ -0,0 +1,20 @@
+AC_DEFUN([GP_CHECK_GEANYPY],
+[
+    GP_ARG_DISABLE([Geanypy], [auto])
+    GP_CHECK_PLUGIN_GTK2_ONLY([Geanypy])
+    GP_COMMIT_PLUGIN_STATUS([Geanypy])
+    PKG_CHECK_MODULES([PYGTK], [pygtk-2.0])
+    AX_PYTHON_DEVEL([>= '2.6'])
+    AX_PYTHON_LIBRARY(,[AC_MSG_ERROR([Cannot find Python library])])
+    AC_SUBST([PYTHON])
+	AC_DEFINE_UNQUOTED(
+	    [GEANYPY_PYTHON_LIBRARY],
+	    ["$PYTHON_LIBRARY"],
+	    [Location of Python library to dlopen()])
+    AC_CONFIG_FILES([
+        geanypy/Makefile
+        geanypy/src/Makefile
+        geanypy/geany/Makefile
+        geanypy/plugins/Makefile
+    ])
+])

configure.ac

@@ -41,6 +41,7 @@ GP_CHECK_GEANYMACRO
 GP_CHECK_GEANYMINISCRIPT
 GP_CHECK_GEANYNUMBEREDBOOKMARKS
 GP_CHECK_GEANYPRJ
+GP_CHECK_GEANYPY
 GP_CHECK_GEANYSENDMAIL
 GP_CHECK_GEANYVC
 GP_CHECK_GEANYPG

geanypy/AUTHORS

@@ -0,0 +1,2 @@
+Matthew Brush <mbrush@codebrainz.ca>
+Lex Trotman <elextr@gmail.com> (Geany-Plugins port)

geanypy/ChangeLog

@@ -0,0 +1 @@
+Unused

geanypy/Makefile.am

@@ -0,0 +1,4 @@
+include $(top_srcdir)/build/vars.auxfiles.mk
+#ACLOCAL_AMFLAGS += -I geanypy/m4
+SUBDIRS = src geany plugins
+plugin = geanypy

geanypy/NEWS

@@ -0,0 +1 @@
+UnNEWSed

geanypy/README

@@ -0,0 +1,73 @@
+GeanyPy
+=======
+
+Write Geany plugins in Python!
+
+Provides most of the standard Geany C API for Python.
+
+**Please note:** GeanyPy here in geany-plugins is based on the upstream 
+at https://github.com/codebrainz/geanypy which is still under 
+development, however it is useful as is.  Parts of the existing API 
+which mirror the Geany C API will probably not change unless the Geany API 
+changes, however new API may be added.  Also documentation is needed, 
+contributions are welcome.
+
+How it works
+------------
+
+In the ``src/`` directory is a normal Geany plugin (``plugin.c``) which loads the
+Python interpreter.  It then loads some C Python modules (``dialogs.c``,
+``documents.c``, etc.) that interface with Geany's C API.  After that, it loads
+the ``geany`` Python module which is just glue/sugar-coating to make the C
+module more "Pythonic".
+
+To write a plugin, inherit from the ``geany.Plugin`` class and implmenent the
+required members (see ``geany/plugin.py`` documentation comments).  Then put the
+plugin in a searched plugin path.  Currently two locations are search for
+plugins.  The first is ``PREFIX/share/geany/geanypy/plugins`` and the recommended
+location is under your personal Geany directory (usually
+``~/.config/geany/plugins/geanypy/plugins``).  To load or unload plugins, click
+the Python Plugin Manager item under the Tools menu which will appear when you
+activate GeanyPy through Geany's regular plugin manager.
+
+When the GeanyPy plugin is loaded, it has an option to add a new tab to 
+the notebook in the message window area that contains an interactive 
+Python shell with the ``geany`` module pre-imported.  You can tinker 
+around with API with this console, for example::
+
+
+    import geany
+
+    doc = geany.document.open_file("/some/file/here")
+
+    print(doc.file_name)
+    print(doc.file_type.display_name)
+
+    geany.dialogs.show_msgbox("Hello World")
+
+    geany.main_widgets.window.set_title("Hello Window")
+
+    def on_document_open(doc):
+        print("Document '%s' was opened" % doc.file_name)
+
+    geany.signals.connect('document-open', on_document_open)
+
+
+Dependencies
+------------
+
+To build GeanyPy you need the following dependencies:
+
+* Python 2.6 or 2.7 and development files.
+* Geany 1.24+ and development files
+* PyGTK 2.0 and development files
+
+Running on Windows
+------------------
+
+Not currently supported for the geany-plugins version, see upstream 
+https://github.com/codebrainz/geanypy.
+
+Upstream developed by Matthew Brush.
+
+Geany-plugins version maintained by elextr@lists.geany.org

geanypy/doc/make.bat

@@ -0,0 +1,170 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\GeanyPy.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\GeanyPy.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

geanypy/doc/source/api.rst

@@ -0,0 +1,67 @@
+API Documentation
+*****************
+
+GeanyPy's API mimics quite closely Geany's C plugin API.  The following
+documentation is broken down by file/module:
+
+The :mod:`geany` modules:
+
+.. toctree::
+    :maxdepth: 2
+
+    app.rst
+    dialogs.rst
+    document.rst
+
+The :mod:`geany` package and module
+===================================
+
+.. module:: geany
+
+All of GeanyPy's bindings are inside the :mod:`geany` package which also
+contains some stuff in it's :mod:`__init__` file, acting like a module itself.
+
+
+.. data:: app
+
+    An instance of :class:`app.App` to store application information.
+
+.. data:: main_widgets
+
+    An instance of :class:`mainwidgets.MainWidgets` to provide access to
+    Geany's important GTK+ widgets.
+
+.. data:: signals
+
+    An instance of :class:`signalmanager.SignalManager` which manages the
+    connection, disconnection, and emission of Geany's signals.  You can
+    use this as follows::
+
+        geany.signals.connect('document-open', some_callback_function)
+
+.. function:: is_realized()
+
+    This function, which is actually in the :mod:`geany.main` module will tell
+    you if Geany's main window is realized (shown).
+
+.. function:: locale_init()
+
+    Again, from the :mod:`geany.main` module, this will initialize the `gettext`
+    translation system.
+
+.. function:: reload_configuration()
+
+    Also from the :mod:`geany.main` module, this function will cause Geany to
+    reload most if it's configuration files without restarting.
+
+    Currently the following files are reloaded:
+
+        * all template files
+        * new file templates
+        * the New (with template) menus will be updated
+        * Snippets (snippets.conf)
+        * filetype extensions (filetype_extensions.conf)
+        * `settings` and `build_settings` sections of the filetype definition files.
+
+    Plugins may call this function if they changed any of these files (e.g. a
+    configuration file editor plugin).