Start documenting

GENERATING_MODULES.md

@@ -0,0 +1,36 @@
+# Generating Modules with pfsensible-generate-module
+
+The process of writing basic pfsensible modules is hopefully greately simplified by using
+the pfsensible-generate-module script. The basic workflow is as follows:
+
+* Navigate in the pfSense web interface to the area you want to write a module for. This should be a page where you can edit
+settings or one where you are adding an item.
+* Copy the URL of the page - you will pass it to the --url option of the script.
+
+## Modules that manage multiple items
+
+If this is a module that will allow you to create multiple items (e.g. aliases, rules):
+* Save a minimal item with a name (often Name or Description) of "item_min" (or something else if that does not work).
+Simply try immediately saving an item with just that name, then fill out fields one at a time and re-save until pfSense
+stops complaining about missing items.
+* Save a "fully" configured item with a name of "item_full" (or something else if that will not work). It may be
+helpful to change as many options away from the default as possible. Focus on settings that would be useful to you.
+* Run the script:
+
+ misc/pfsensible-generate-module --url URL
+
+if you needed to use different names for the items than "item_min" and "item_full" you can set them with the --item-min and
+--item-full options.
+
+## Modules that configure something
+
+If this is a module that will just configure something, add the --is-config option.
+
+## Other options
+
+* Pass the --author-name, --author-email, and --author-handle options.
+* You will need to add the --user and/or --password options if you have changed from the install defaults.
+* If the automatically determined module name does not seem correct, you can change it with the --module-name option.
+* It may make sense to create a module for different types of items if the parameters are wildly different (as is the case
+with the different types of authentication servers for example). If so, add the --type-suffix option to add the "type"
+of the item as a suffix to the module name.

README.md

@@ -103,6 +103,11 @@ These modules allow you to manage installed packages:
 
 ## [Change Log](https://github.com/pfsensible/core/blob/master/CHANGELOG.rst)
 
+## Writing new modules
+
+See [GENERATING_MODULES](https://github.com/pfsensible/core/blob/master/GENERATING_MODULES.md) for instructions on how to use the
+pfensible-generate-module script to automate the task writing basic pfsensible modules.
+
 ## Operation
 
 Modules in the collection work by editing `/cf/conf/config.xml` using xml.etree.ElementTree, then