document xstatic packaging, some other doc fixes

3 files changed, 104 insertions, 4 deletions

diff --git a/docs/source/index.rst b/docs/source/index.rst
index d048b63..63f0602 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -16,6 +16,7 @@ Using XStatic
    :maxdepth: 2
 
    using
+   packaging
 
 
 Indices and tables
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 64ceffd..e87f2e6 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -25,7 +25,7 @@ they won't be required if you just want the files.
 
 By having static files in packages, it is also easier to build virtual envs,
 support linux/bsd/... distribution package maintainers and even windows installs
-using the same mechanisms.
+using the same mechanism.
 
 Pros
 ====
@@ -38,11 +38,11 @@ Pros
   your stuff into separate packages, so they don't need to
 * outsource some work to other people. there are lots of people needing these
   static packages, so you don't need to maintain them all yourself.
-* additionally to the files, you'll get some more-or-less metadata (like
-  version info, name, CDN URLs (if any).
+* additionally to the files, you'll get some metadata (like version info, name,
+  CDN URLs (if any).
 * we can use version number of the package to reflect the version of the packaged
   static stuff and use the packaging system to require some specific version,
-  or some specific minimum version.
+  or some specific minimum/maximum version.
 * security updates are easier, the static file packages can be updated separately
   from your main package.
 
diff --git a/docs/source/packaging.rst b/docs/source/packaging.rst
new file mode 100644
index 0000000..d4299d0
--- /dev/null
+++ b/docs/source/packaging.rst
@@ -0,0 +1,99 @@
+Packaging for XStatic
+=====================
+
+It's easy, no rocket-scientist needed.
+
+We suggest you just take XStatic-jQuery package as a template and do these
+steps:
+
+* Copy XStatic-jQuery to XStatic-FooBar (replace "FooBar" by the official name
+  [display_name] of the project you are packaging).
+* Rename xstatic/pkg/jquery package directory to xstatic/pkg/foobar (use
+  simple all-lowercase name, only a..z - this must be a valid python package
+  name [name]).
+* Remove xstatic/pkg/foobar/data/* and place FooBar project's static files
+  there.
+* Edit xstatic/pkg/foobar/__init__.py and update all information there
+  appropriately (see the comments there and also the hints below).
+  Most stuff from there will get reused by setup.py.
+  Do not forget to use some appropriate class name.
+* Edit setup.py:
+
+  - You need to change the "from xstatic.pkg..." appropriately to import your
+    class.
+  - Review the rest of it, but most stuff should be fine as it just reuses
+    stuff from XStatic metadata.
+* Edit MANIFEST.in and change the recursive-include statement there to refer
+  to your files (xstatic/pkg/foobar), so that your static files will be
+  included in the package created later.
+* Edit README.txt and replace references to jQuery with FooBar.
+  This file's content will also be shown as long description on PyPi.
+* If you use Mercurial, update .hgignore so it ignores:
+  ^XStatic_FooBar.egg-info/
+* Review all the stuff you did, make sure you did not forget anything, make
+  sure there is no jquery reference left.
+* Run python setup.py sdist.
+* Look into build/... - there should be your XStatic-FooBar package now.
+* Test it locally:
+
+  - E.g. use pip install XStatic-FooBar-1.0.0.tar.gz to install it.
+  - Use it from your project, does it work?
+* If you are happy with it and you think the package is also useful for many
+  other Pythonistas, register and upload it to PyPi:
+  python setup.py sdist register upload
+
+Misc. Hints
+===========
+
+Names
+-----
+There are 3 names involved and you should follow these rules:
+
+* XStatic subclass name: choose something starting with a uppercase letter
+  to follow PEP8 naming convention. E.g. FooBar or JQuery, not foobar nor
+  jQuery.
+* name (metadata): simple, all lowercase name. E.g. foobar or jquery.
+  If you would have to use "-": please replace it by "_". Minus is not valid
+  in Python package names, so use underscore so that you can use same name
+  for your package directory / package name.
+* display_name (metadata): the name as the upstream project itself spells it,
+  e.g. jQuery or FooBar. No spaces.
+
+Version Numbers
+---------------
+As you are just repackaging another project, you should use the upstream
+version number (or at least something closely related to it).
+
+As you maybe do not get packaging right on the first try, we suggest appending
+a build number, like:
+
+* Upstream version: 1.2.3, XStatic-FooBar version: 1.2.3.0 (initial package)
+* Upstream version: 1.2.3, XStatic-FooBar version: 1.2.3.1 (fixed package)
+* Upstream version: 1.2.4, XStatic-FooBar version: 1.2.4.0 (initial package)
+
+Some projects do not have such version numbers, make the best of it:
+
+* Upstream version: 2010-12-31, XStatic-FooBar version: 2011.12.31.0
+
+Which files to put into your package?
+-------------------------------------
+It is suggested that you only package files that are useful for Python
+projects, because XStatic packages will be only used by them. No need for PHP,
+ASP, Java, etc. related files.
+
+If you package files that are somehow "compiled/compressed" versions, we
+suggest you only package the files needed for production usage, not the source
+code.
+
+If the original download archive has the files needed for production in some
+subdirectory, we suggest you strip the directory hierarchy and just put the
+production files/directories into xstatic/pkg/foobar/data/.
+
+CDN locations
+-------------
+If your files are available via a public CDN (Content Distribution Network),
+you can give the URLs via the locations metadata.
+
+If you do not have a CDN for the files, just use locations = {}.
+
+