Merge 5433a5a into 1f46dbd

.travis.yml

@@ -31,3 +31,5 @@ env:
   - TOXENV=py35-django19
   - TOXENV=py35-django110
 
+  - TOXENV=docs
+

Changelog.rst

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+1.4 (beta)
+----------
+
+* ``--template``, ``-t`` option added to management commands. These limit the
+  templates that are parsed for ``{% systemjs_import ... %}`` tags.
+
+* Added ``--minimal`` option to ``systemjs_bundle`` management command. This will
+  rebundle an app/package only when something has changed in the dependency tree.
+  Usefull when you have many bundles and only a small number changed.
+
+* Added two new management commands:
+
+  - ``systemjs_show_packages``: lists all the packages imported in templates
+  - ``systemjs_write_depcaches``: writes out the dependency tree for each package
+
 1.3.3
 -----
 

bin/trace-deps.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Utility script to leverage jpsm/SystemJS' power to build the depcache
+ * for a given package.
+ *
+ * This traces the module and extracts the relative paths to all the
+ * files used.
+ */
+
+var fs = require('fs');
+var Builder = require('jspm').Builder;
+
+
+var jsapp = process.argv[2];  // 0 is node, 1 is the file
+
+
+var builder = new Builder();
+builder.trace(jsapp).then(function(trace) {
+    var deps = {}
+    for( var jsapp in trace ) {
+        var skip = trace[jsapp] === false; // e.g. with google maps, see #13
+        deps[jsapp] = {
+            name: jsapp,
+            timestamp: skip ? null : trace[jsapp].timestamp,
+            path: skip ? null : trace[jsapp].path,
+            skip: skip
+        };
+    }
+    process.stdout.write(JSON.stringify(deps, null));
+});

docs/_ext/djangodocs.py

@@ -0,0 +1,79 @@
+"""
+Taken from djangoproject/django docs.
+"""
+
+"""
+Sphinx plugins for Django documentation.
+"""
+import json
+import os
+import re
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.domains.std import Cmdoption
+from sphinx.util.compat import Directive
+from sphinx.util.console import bold
+from sphinx.util.nodes import set_source_info
+from sphinx.writers.html import SmartyPantsHTMLTranslator
+
+# RE for option descriptions without a '--' prefix
+simple_option_desc_re = re.compile(
+    r'([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)')
+
+
+def setup(app):
+    app.add_directive('versionadded', VersionDirective)
+    app.add_directive('versionchanged', VersionDirective)
+    return {'parallel_read_safe': True}
+
+
+class VersionDirective(Directive):
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        if len(self.arguments) > 1:
+            msg = """Only one argument accepted for directive '{directive_name}::'.
+            Comments should be provided as content,
+            not as an extra argument.""".format(directive_name=self.name)
+            raise self.error(msg)
+
+        env = self.state.document.settings.env
+        ret = []
+        node = addnodes.versionmodified()
+        ret.append(node)
+        node['version'] = self.arguments[0]
+        node['type'] = self.name
+        if self.content:
+            self.state.nested_parse(self.content, self.content_offset, node)
+        env.note_versionchange(node['type'], node['version'], node, self.lineno)
+        return ret
+
+
+class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
+
+    version_text = {
+        'versionchanged': 'Changed in %s',
+        'versionadded': 'Added in %s',
+    }
+
+    def visit_versionmodified(self, node):
+        self.body.append(
+            self.starttag(node, 'div', CLASS=node['type'])
+        )
+        version_text = self.version_text.get(node['type'])
+        if version_text:
+            title = "%s%s" % (
+                version_text % node['version'],
+                ":" if len(node) else "."
+            )
+            self.body.append('<span class="title">%s</span> ' % title)
+
+    def depart_versionmodified(self, node):
+        self.body.append("</div>\n")

docs/_theme/djangodocs/static/default.css

@@ -0,0 +1 @@
+@import url(djangodocs.css);

docs/_theme/djangodocs/static/djangodocs.css

@@ -0,0 +1,4 @@
+/*** versionadded/changes ***/
+div.versionadded, div.versionchanged {  }
+div.versionadded span.title, div.versionchanged span.title, span.versionmodified { font-weight: bold; }
+div.versionadded, div.versionchanged, div.deprecated { color:#555; }

docs/_theme/djangodocs/theme.conf

@@ -0,0 +1,4 @@
+[theme]
+inherit = sphinx_rtd_theme
+# stylesheet = default.css
+# pygments_style = trac

docs/conf.py

@@ -15,6 +15,9 @@
 import sys
 import os
 import shlex
+from os.path import abspath, join, dirname
+
+sys.path.append(abspath(join(dirname(__file__), "_ext")))
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -29,7 +32,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+  "djangodocs"
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -55,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.3.0'
+version = '1.4'
 # The full version, including alpha/beta/rc tags.
-release = '1.3.0'
+release = '1.4beta6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -100,6 +105,8 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+suppress_warnings = ['image.nonlocal_uri', 'app.add_directive']
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
@@ -108,15 +115,15 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+# html_theme = 'djangodocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# html_theme_path = ["_theme"]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -137,7 +144,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -150,7 +157,10 @@
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-#html_use_smartypants = True
+html_use_smartypants = True
+
+# HTML translator class for the builder
+html_translator_class = "djangodocs.DjangoHTMLTranslator"
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
@@ -291,5 +301,7 @@
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    # html_theme = 'djangodocs'
+    # html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + html_theme_path
 
 # otherwise, readthedocs.org uses their theme by default, so no need to specify it

docs/config.rst

@@ -0,0 +1,43 @@
+.. _available-settings:
+
+==================
+Available settings
+==================
+
+``SYSTEMJS_ENABLED``: defaults to ``not settings.DEBUG``. If disabled, the loading
+of modules will happen in the 'standard' jspm way (transpiling in browser).
+
+``SYSTEMJS_JSPM_EXECUTABLE``: path to the ``jspm-cli`` executable. Defaults to
+``jspm``, which should be available if installed globally with ``npm``.
+
+``SYSTEMJS_OUTPUT_DIR``: name of the subdirectory within ``settings.STATIC_ROOT``.
+Bundled files will end up in this directory, and this is the place the
+templatetag will point static files to.
+
+``SYSTEMJS_PACKAGE_JSON_DIR``: directory containing your ``package.json`` file.
+This is automatically guessed from ``BASE_DIR``. You will get an error in the
+shell if you need to set it yourself.
+
+``SYSTEMJS_DEFAULT_JS_EXTENSIONS``: in prior verions of jspm, the ``.js`` extension
+for imports was optional. This is being phased out, and matches the
+``defaultJSExtensions`` settings in ``config.js``.
+
+``CACHE_DIR``: directory to keep the dependency cache (when generating
+:ref:`minimal <minimal>` bundles)
+
+
+Environment variables
+=====================
+
+``NODE_PATH``
+-------------
+
+When generating :ref:`minimal <minimal>` bundles, a NodeJS script
+(``trace-deps.js``) is called. This script needs to be called from the directory
+containing ``package.json``. If Django-SystemJS cannot figure out this directory
+by itself, you may need to set the environment variable:
+
+.. code-block:: sh
+
+    export NODE_PATH=/path/to/project/node_modules
+