Enable specific documenting of __call__() methods

doc/source/conf.py

@@ -31,7 +31,6 @@
 import os
 import inspect
 import six
-from sphinx import apidoc
 
 # 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
@@ -376,28 +375,47 @@ def setup(app):
     app.connect('autodoc-skip-member', maybe_skip)
 
 
+# We want to document __call__ when encountered
+autodoc_default_options = {
+    "members": True,
+    "special-members": "__call__"
+}
+
 # Do the rst generation
 for f in os.listdir("."):
     if (os.path.isfile(f) and f.endswith(
             ".rst") and f != "index.rst" and f != "modules.rst"):
         os.remove(f)
-base = "../../" + root_package
-apidoc.main([None, '-o', ".", base,
-             base + "/executor/a*/[a-z]*.py",
-             base + "/executor/*reader.py",
-             base + "/executor/[b-z]*.py",
-             base + "/model/*_constraints/[a-z]*.py",
-             base + "/model/constraints/abstract_constraint.py",
-             base + "/model/decorators/*",
-             base + "/model/graphs/*/[a-z]*.py",
-             base + "/model/graphs/abstract_*.py",
-             base + "/model/graphs/[go]*.py",
-             base + "/model/placements/[a-z]*.py",
-             base + "/model/resources/[a-z]*.py",
-             base + "/model/routing_*/[a-z]*.py",
-             base + "/model/tags/[a-z]*.py",
-             base + "/operations/router_compressors/[a-ep-z]*.py",
-             base + "/operations/router_compressors/malloc*.py",
-             base + "/operations/router_compressors/m*/[a-z]*.py",
-             base + "/utilities/utility_objs/[a-z]*.py",
-             ])
+
+# UGH!
+output_dir = os.path.abspath(".")
+os.chdir("../..")
+
+options = [
+    '-o', output_dir, root_package,
+    "pacman/executor/a*/[a-z]*.py",
+    "pacman/executor/*reader.py",
+    "pacman/executor/[b-z]*.py",
+    "pacman/model/*_constraints/[a-z]*.py",
+    "pacman/model/constraints/abstract_constraint.py",
+    "pacman/model/decorators/*",
+    "pacman/model/graphs/*/[a-z]*.py",
+    "pacman/model/graphs/abstract_*.py",
+    "pacman/model/graphs/[go]*.py",
+    "pacman/model/placements/[a-z]*.py",
+    "pacman/model/resources/[a-z]*.py",
+    "pacman/model/routing_*/[a-z]*.py",
+    "pacman/model/tags/[a-z]*.py",
+    "pacman/operations/router_compressors/[a-ep-z]*.py",
+    "pacman/operations/router_compressors/malloc*.py",
+    "pacman/operations/router_compressors/m*/[a-z]*.py",
+    "pacman/utilities/utility_objs/[a-z]*.py",
+    ]
+try:
+    # Old style API; Python 2.7
+    from sphinx import apidoc
+    options = [None] + options
+except ImportError:
+    # New style API; Python 3.6 onwards
+    from sphinx.ext import apidoc
+apidoc.main(options)

doc/source/index.rst

@@ -13,6 +13,7 @@ PACMAN
 ======
 
 .. automodule:: pacman
+	:noindex:
 
 Contents:
 

pacman/model/resources/abstract_sdram.py

@@ -69,7 +69,7 @@ def fixed(self):
     def per_timestep(self):
         """ Returns extra SDRAM cost for each additional timestep
 
-        .. warn:
+        .. warning::
             May well be zero.
         """
 

pacman/operations/algorithm_reports/network_specification.py

@@ -23,9 +23,6 @@
 
 class NetworkSpecification(object):
     """ Generate report on the user's network specification.
-
-    :param str report_folder: the directory to which reports are stored
-    :param ApplicationGraph graph: the graph generated from the tools
     """
 
     _FILENAME = "network_specification.rpt"

pacman/operations/algorithm_reports/router_collision_potential_report.py

@@ -23,6 +23,12 @@ class RouterCollisionPotentialReport(object):
     def __call__(
             self, router_tables_by_partition, n_keys_map,
             default_report_folder, machine):
+        """
+        :param MulticastRoutingTableByPartition router_tables_by_partition:
+        :param AbstractMachinePartitionNKeysMap n_keys_map:
+        :param str default_report_folder:
+        :param ~spinn_machine.Machine machine:
+        """
         file_name = os.path.join(
             default_report_folder, "routing_collision_protential_report.rpt")
 

pacman/operations/algorithm_reports/write_json_machine.py

@@ -28,22 +28,18 @@ class WriteJsonMachine(object):
     .. note::
         This is no longer the rig machine format!
 
-    :param ~spinn_machine.Machine machine: Machine to convert
-    :param str json_folder:
-        The folder to which the JSON are being written.
-
-        .. warn:
-             The files in this folder will be overwritten!
-
-    :return: the name of the generated file
-    :rtype: str
     """
 
     def __call__(self, machine, json_folder):
         """ Runs the code to write the machine in readable JSON.
 
-        :param ~spinn_machine.Machine machine:
-        :param str json_folder:
+        :param ~spinn_machine.Machine machine: Machine to convert
+        :param str json_folder: The folder to which the JSON are being written.
+
+            .. warning::
+                 The files in this folder will be overwritten!
+
+        :return: the name of the generated file
         :rtype: str
         """
         # Steps are tojson, validate and writefile

pacman/operations/algorithm_reports/write_json_machine_graph.py

@@ -29,16 +29,16 @@
 class WriteJsonMachineGraph(object):
     """ Converter (:py:obj:`callable`) from :py:class:`MulticastRoutingTables`
         to JSON.
-
-    :param MachineGraph machine_graph: The machine_graph to place
-    :param str json_folder:
-        The folder to which the reports are being written
-    :return: The name of the actual file that was written
-    :rtype: str
     """
 
     def __call__(self, machine_graph, json_folder):
         """ Runs the code to write the machine in Java readable JSON.
+
+        :param MachineGraph machine_graph: The machine_graph to place
+        :param str json_folder:
+            The folder to which the reports are being written
+        :return: The name of the actual file that was written
+        :rtype: str
         """
         # Steps are tojson, validate and writefile
         progress = ProgressBar(3, "Converting to JSON MachineGraph")
@@ -52,7 +52,7 @@ def write_json(machine_graph, json_folder, progress=None):
 
         :param MachineGraph machine_graph: The machine_graph to place
         :param str json_folder:
-            The folder to which the json are being written
+            The folder to which the JSON are being written
 
             .. warning::
                 Will overwrite existing file in this folder!

pacman/operations/algorithm_reports/write_json_partition_n_keys_map.py

@@ -28,19 +28,15 @@
 
 class WriteJsonPartitionNKeysMap(object):
     """ Converter from MulticastRoutingTables to JSON.
-
-    :param AbstractMachinePartitionNKeysMap partition_to_n_keys_map:
-        The number of keys needed for each partition.
-    :param str json_folder: the folder to which the JSON are being written
-    :return: the name of the generated file
-    :rtype: str
     """
 
     def __call__(self, partition_to_n_keys_map, json_folder):
         """ Runs the code to write the n_keys_map in JSON.
 
         :param AbstractMachinePartitionNKeysMap partition_to_n_keys_map:
-        :param str json_folder:
+            The number of keys needed for each partition.
+        :param str json_folder: the folder to which the JSON are being written
+        :return: the name of the generated file
         :rtype: str
         """
         # Steps are tojson, validate and writefile

pacman/operations/algorithm_reports/write_json_placements.py

@@ -28,18 +28,14 @@
 
 class WriteJsonPlacements(object):
     """ Converter from Placements to JSON.
-
-    :param Placements placements: The placements to write.
-    :param str json_folder: The folder to which the JSON are being written.
-    :return: The name of the generated file.
-    :rtype: str
     """
 
     def __call__(self, placements, json_folder):
         """ Runs the code to write the placements in JSON.
 
-        :param Placements placements:
-        :param str json_folder:
+        :param Placements placements: The placements to write.
+        :param str json_folder: The folder to which the JSON are being written.
+        :return: The name of the generated file.
         :rtype: str
         """
         # Steps are tojson, validate and writefile

pacman/operations/algorithm_reports/write_json_routing_tables.py

@@ -24,19 +24,15 @@
 
 class WriteJsonRoutingTables(object):
     """ Converter from MulticastRoutingTables to JSON.
-
-    :param MulticastRoutingTables router_tables:
-        Routing Tables to convert
-    :param str json_folder: the folder to which the JSON are being written
-    :return: the name of the generated file
-    :rtype: str
     """
 
     def __call__(self, router_tables, json_folder):
         """ Runs the code to write the machine in Java readable JSON.
 
         :param MulticastRoutingTables router_tables:
-        :param str json_folder:
+            Routing Tables to convert
+        :param str json_folder: the folder to which the JSON are being written
+        :return: the name of the generated file
         :rtype: str
         """
         # Steps are tojson, validate and writefile

pacman/operations/chip_id_allocator_algorithms/malloc_based_chip_id_allocator.py

@@ -58,12 +58,25 @@ def __init__(self):
         self._virtual_chips = dict()
 
     def __call__(self, machine, graph=None):
+        """
+        :param ~spinn_machine.Machine machine:
+        :param graph:
+        :type graph: Graph or None
+        :rtype: ~spinn_machine.Machine
+        :raises PacmanConfigurationException:
+            If a virtual chip is in an impossible position.
+        """
         if graph is not None:
             self.allocate_chip_ids(machine, graph)
         return machine
 
     def allocate_chip_ids(self, machine, graph):
         """ Go through the chips (real and virtual) and allocate keys for each
+
+        :param ~spinn_machine.Machine machine:
+        :param Graph graph:
+        :raises PacmanConfigurationException:
+            If a virtual chip is in an impossible position.
         """
         progress = ProgressBar(
             graph.n_vertices + machine.n_chips,

pacman/operations/fixed_route_router/fixed_route_router.py

@@ -23,16 +23,6 @@
 class FixedRouteRouter(object):
     """ Computes the fixed routes used to direct data out traffic to the
         board-local gatherer processors.
-
-    :param ~spinn_machine.Machine machine: SpiNNMachine object
-    :param Placements placements: placements object
-    :param destination_class: the destination class to route packets to
-    :type destination_class: type or tuple(type,...)
-    :return: router tables for fixed route paths
-    :rtype: dict(tuple(int,int), ~spinn_machine.FixedRouteEntry)
-    :raises PacmanConfigurationException: if no placement processor found
-    :raises PacmanRoutingException:
-    :raises PacmanAlreadyExistsException:
     """
 
     __slots__ = [

pacman/operations/partition_algorithms/basic_partitioner.py

@@ -32,15 +32,6 @@
 class BasicPartitioner(object):
     """ An basic algorithm that can partition an application graph based\
         on the number of atoms in the vertices.
-
-    :param ApplicationGraph graph: The application_graph to partition
-    :param ~spinn_machine.Machine machine:
-        The machine with respect to which to partition the application graph
-    :param int plan_n_timesteps: number of timesteps to plan for
-    :return: A machine graph
-    :rtype: MachineGraph
-    :raise PacmanPartitionException:
-        If something goes wrong with the partitioning
     """
 
     __slots__ = []
@@ -54,11 +45,15 @@ def _get_ratio(top, bottom):
     # inherited from AbstractPartitionAlgorithm
     def __call__(self, graph, machine, plan_n_timesteps):
         """
-        :param ApplicationGraph graph:
+        :param ApplicationGraph graph: The application_graph to partition
         :param ~spinn_machine.Machine machine:
-        :param int plan_n_timesteps:
+            The machine with respect to which to partition the application
+            graph
+        :param int plan_n_timesteps: number of timesteps to plan for
+        :return: A machine graph
         :rtype: MachineGraph
         :raise PacmanPartitionException:
+            If something goes wrong with the partitioning
         """
         ResourceTracker.check_constraints(graph.vertices)
         utility_calls.check_algorithm_can_support_constraints(

pacman/operations/partition_algorithms/partition_and_place_partitioner.py

@@ -39,20 +39,6 @@
 class PartitionAndPlacePartitioner(object):
     """ A partitioner that tries to ensure that SDRAM is not overloaded by\
         keeping track of the SDRAM usage on the various chips
-
-    :param ApplicationGraph graph: The application_graph to partition
-    :param ~spinn_machine.Machine machine:
-        The machine with respect to which to partition the application
-        graph
-    :param int plan_n_timesteps: number of timesteps to plan for
-    :param preallocated_resources:
-    :type preallocated_resources: PreAllocatedResourceContainer or None
-    :return:
-        A machine_graph of partitioned vertices and partitioned edges,
-        and the number of chips needed to satisfy this partitioning.
-    :rtype: tuple(MachineGraph, int)
-    :raise PacmanPartitionException:
-        If something goes wrong with the partitioning
     """
 
     __slots__ = []
@@ -62,13 +48,19 @@ def __call__(
             self, graph, machine, plan_n_timesteps,
             preallocated_resources=None):
         """
-        :param ApplicationGraph graph:
+        :param ApplicationGraph graph: The application_graph to partition
         :param ~spinn_machine.Machine machine:
-        :param int plan_n_timesteps:
+            The machine with respect to which to partition the application
+            graph
+        :param int plan_n_timesteps: number of timesteps to plan for
         :param preallocated_resources:
         :type preallocated_resources: PreAllocatedResourceContainer or None
+        :return:
+            A machine_graph of partitioned vertices and partitioned edges,
+            and the number of chips needed to satisfy this partitioning.
         :rtype: tuple(MachineGraph, int)
         :raise PacmanPartitionException:
+            If something goes wrong with the partitioning
         """
         ResourceTracker.check_constraints(graph.vertices)
         utils.check_algorithm_can_support_constraints(

pacman/operations/placer_algorithms/connective_based_placer.py

@@ -38,18 +38,14 @@ class ConnectiveBasedPlacer(RadialPlacer):
 
     def __call__(self, machine_graph, machine, plan_n_timesteps):
         """
-        :param machine_graph: The machine_graph to place
-        :type machine_graph:\
-            :py:class:`pacman.model.graphs.machine.MachineGraph`
-        :param machine:\
-            The machine with respect to which to partition the application\
+        :param MachineGraph machine_graph: The machine_graph to place
+        :param ~spinn_machine.Machine machine:
+            The machine with respect to which to partition the application
             graph
-        :type machine: :py:class:`spinn_machine.Machine`
-        :param plan_n_timesteps: number of timesteps to plan for
-        :type  plan_n_timesteps: int
+        :param int plan_n_timesteps: number of timesteps to plan for
         :return: A set of placements
-        :rtype: :py:class:`pacman.model.placements.Placements`
-        :raise pacman.exceptions.PacmanPlaceException: \
+        :rtype: ~pacman.model.placements.Placements
+        :raise PacmanPlaceException:
             If something goes wrong with the placement
         """
         # check that the algorithm can handle the constraints