SUBMITTING_WXGUI 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161
  1. NOTE: Please improve this list!
  2. Dear (new) GRASS developer,
  3. when submitting Python code to GRASS SVN repository, please take
  4. care of following rules:
  5. [ see SUBMITTING for C hints ]
  6. [ see SUBMITTING_PYTHON for Python code hints ]
  7. [ see SUBMITTING_DOCS for documentation ]
  8. 0. Introduction
  9. For general GRASS, svn and Python issues and module related issues see
  10. SUBMITTING_PYTHON and SUBMITTING.
  11. GUI is divided into components. One component is usually placed in one
  12. directory.
  13. 1. GRASS documentation
  14. GRASS Programming manual for API and existing classes
  15. http://grass.osgeo.org/programming7/wxpythonlib.html
  16. GRASS wiki has pages about how to develop wxGUI
  17. http://grasswiki.osgeo.org
  18. GRASS Trac wiki has pages about the state of wxGUI development
  19. http://trac.osgeo.org/grass/wiki/wxGUIDevelopment
  20. 2. External documentation
  21. Style Guide for Python Code
  22. http://www.python.org/dev/peps/pep-0008/
  23. Python Style Guide by Guido van Rossum
  24. http://www.python.org/doc/essays/styleguide.html
  25. wxPython Style Guide
  26. http://wiki.wxpython.org/wxPython_Style_Guide
  27. Additional info on Python docstrings
  28. http://epydoc.sourceforge.net/docstrings.html
  29. 3. Remember that functionality such as generating plots should be primarily
  30. provided by modules not GUI.
  31. 4. Try to create create also g.gui.* module for the new GUI component. It helps
  32. advanced users to access functionality and developers to test it. Moreover,
  33. it helps to keep components separated and thus, supports re-usability.
  34. 5. Add a header section to each file you submit and make sure you
  35. include the copyright. The purpose section is meant to contain a
  36. general over view of the code in the file to assist other
  37. programmers that will need to make changes to your code. For this
  38. purpose use Python docstring.
  39. The copyright protects your rights according to GNU General Public
  40. License (www.gnu.org).
  41. Please use the following docstring template:
  42. """!
  43. @package dir.example
  44. @brief Short example package description
  45. Classes:
  46. - example::ExampleClass
  47. (C) 2012 by the GRASS Development Team
  48. This program is free software under the GNU General Public License
  49. (>=v2). Read the file COPYING that comes with GRASS for details.
  50. @author First Author <first somewhere.com>
  51. @author Second Author <second somewhere.com>
  52. @author Some Other <third somewhere.com> (some particular change)
  53. """
  54. 6. Comment your classes and functions with docstrings. Use Doxygen syntax,
  55. particularly, use commands which begins with @
  56. (www.doxygen.org/manual/commands.html).
  57. Comment also the code itself such as the meaning of variables,
  58. conditions etc.
  59. 7. Make sure a new line is at the end of each file. Non empty line breaks the
  60. build process.
  61. 8. Basic rules
  62. Do not use print command unless you know what are you doing.
  63. Use named parameters in functions (without space around '='), e.g.
  64. dlg = wx.FileDialog(parent=self, message=_("Choose file to save current workspace"),
  65. wildcard=_("GRASS Workspace File (*.gxw)|*.gxw"), style=wx.FD_SAVE)
  66. instead of
  67. dlg = wx.FileDialog(self, _("Choose file to save current workspace"),
  68. _("GRASS Workspace File (*.gxw)|*.gxw"), wx.FD_SAVE)
  69. Use wx.ID_ANY instead of `-1`.
  70. Use GError, GWarning and GMessage instead of wx.MessageBox()
  71. Do not use grass.run_command() or grass.read_command(). Use functions and
  72. classes which uses threads such as RunCommand.
  73. Use full strings, e.g.
  74. if ...:
  75. win.SetLabel(_('Name for new 3D raster map to create'))
  76. else:
  77. win.SetLabel(_('Name for new raster map to create'))
  78. instead of
  79. _('Name for new %s to create') % maplabel
  80. where `maplabel` can be 'raster map' or '3D raster map'
  81. When using AddGrowableCol/AddGrowableRow with sizers, put it after
  82. adding widgets into the sizer, not just after creating of the sizer
  83. (needed for wxPython >= 2.9).
  84. 9. Use tools such as pylint and pep8 to check your code (both style and
  85. correctness). Just note that default settings of these tools is not fully
  86. compatible with wxGUI/wxPython style and that some of the reported errors
  87. may not apply to your code.
  88. 14. Tell the other developers about the new code using the following e-mail:
  89. grass-dev@lists.osgeo.org
  90. To subscribe to this mailing list, see
  91. http://lists.osgeo.org/mailman/listinfo/grass-dev
  92. 15. In case of questions feel free to contact the other developers at the above
  93. mailing list.
  94. http://grass.osgeo.org/devel/index.php#submission
  95. [please add further hints if required]
  96. "Your attention to detail is appreciated."