Add docs for better namespace support

Author: seddonym

README.rst

@@ -114,20 +114,37 @@ You may analyse multiple root packages. To do this, pass each package name as a
 Namespace packages
 ------------------
 
-Graphs can also be built from `portions`_ of `namespace packages`_. To do this, provide the portion name, rather than the namespace name::
-
-    >>> graph = grimp.build_graph('somenamespace.foo')
+Graphs can be built either from `namespace packages`_ or from their `portions`_.
 
 What's a namespace package?
 ###########################
 
-Namespace packages are a Python feature allows subpackages to be distributed independently, while still importable under a shared namespace. This is, for example, used by `the Python client for Google's Cloud Logging API`_. When installed, it is importable in Python as ``google.cloud.logging``. The parent packages ``google`` and ``google.cloud`` are both namespace packages, while ``google.cloud.logging`` is known as the 'portion'. Other portions in the same namespace can be installed separately, for example ``google.cloud.secretmanager``.
+Namespace packages are a Python feature allows subpackages to be distributed independently, while
+still importable under a shared namespace.
+
+This is used by
+`the Python client for Google's Cloud Logging API`_, for example. When installed, it is importable
+in Python as ``google.cloud.logging``. The parent packages ``google`` and ``google.cloud`` are both namespace
+packages, while ``google.cloud.logging`` is known as the 'portion'. Other portions in the same
+namespace can be installed separately, for example ``google.cloud.secretmanager``.
+
+Examples::
+
+    # In this one, the portion is supplied. Neither "google" nor "google.cloud"
+    # will appear in the graph.
+    >>> graph = grimp.build_graph("google.cloud.logging")
+
+    # In this one, a namespace is supplied.
+    # Neither "google" nor "google.cloud" will appear in the graph,
+    # as will other installed packages under the "google" namespace such
+    # as "google.auth".
+    >>> graph = grimp.build_graph("google")
 
-Grimp expects the package name passed to ``build_graph`` to be a portion, rather than a namespace package. So in the case of the example above, the graph should be built like so::
+    # This one supplies a subnamespace of "google" - it will include
+    # "google.cloud.logging" and "google.cloud.secretmanager" but not "google.auth".
+    >>> graph = grimp.build_graph("google.cloud")
 
-    >>> graph = grimp.build_graph('google.cloud.logging')
 
-If, instead, a namespace package is passed (e.g. ``grimp.build_graph('google.cloud')``), Grimp will raise ``NamespacePackageEncountered``.
 
 .. _portions: https://docs.python.org/3/glossary.html#term-portion
 .. _namespace packages: https://docs.python.org/3/glossary.html#term-namespace-package

docs/usage.rst

@@ -57,19 +57,20 @@ Building the graph
     Build and return an ImportGraph for the supplied package or packages.
 
     :param str package_name: The name of an importable package, for example ``'mypackage'``. For regular packages, this
-        must be the top level package (i.e. one with no dots in its name). However, in the special case of
-        `namespace packages`_, the name of the *portion* should be supplied, for example ``'mynamespace.foo'``.
+        must be the top level package (i.e. one with no dots in its name). In the special case of
+        `namespace packages`_, the name of the *portion* may be supplied instead, for example ``'mynamespace.foo'``.
+        If the portion is supplied, its ancestor packages will not be included in the graph.
     :param tuple[str, ...] additional_package_names: Tuple of any additional package names. These can be
         supplied as positional arguments, as in the example above.
     :param bool, optional include_external_packages: Whether to include external packages in the import graph. If this is ``True``,
         any other top level packages (including packages in the standard library) that are imported by this package will
         be included in the graph as squashed modules (see `Terminology`_ above).
 
-        The behaviour is more complex if one of the internal packages is a `namespace portion`_.
+        The behaviour is more complex if one of the specified packages is a `namespace portion`_.
         In this case, the squashed module will have the shallowest name that doesn't clash with any internal modules.
         For example, in a graph with internal packages ``namespace.foo`` and ``namespace.bar.one.green``,
         ``namespace.bar.one.orange.alpha`` would be added to the graph as ``namespace.bar.one.orange``. However, in a graph
-        with only ``namespace.foo`` as an internal package, the same external module would be added as
+        with only ``namespace.foo`` passed, the same external module would be added as
         ``namespace.bar``.
 
         *Note: external packages are only analysed as modules that are imported; any imports they make themselves will

src/grimp/application/usecases.py

@@ -32,7 +32,7 @@ def build_graph(
 
     Args:
         - package_name: the name of the top level package for which to build the graph.
-        - additional_package_names: tuple of the
+        - additional_package_names: tuple of additional packages to build the graph from.
         - include_external_packages: whether to include any external packages in the graph.
         - exclude_type_checking_imports: whether to exclude imports made in type checking guards.
         - cache_dir: The directory to use for caching the graph.