start sphinx docs with travis integration

A new documentation project with Sphinx has been added to the repo, under
the docs/ folder. The .travis.yml file has been updated to also include
building the docs and publishing them to the gh-pages branch, in order
to be published on github pages. Settings of the repository have been changed accordingly.

.travis-docs-script.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# Install PyRDF
+python setup.py install --user
+
+# Install sphinx and sphinx ReadTheDocs theme
+pip install sphinx sphinx_rtd_theme
+
+# Build the docs
+sphinx-build -b html docs docs/build/html

.travis-flake8-script.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# This script is meant to be called by the "install" step defined in
+# This script is meant to be called by the "script" step defined in
 # .travis.yml.
 
 # Install PyRDF

.travis-unit-script.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# This script is meant to be called by the "install" step defined in
+# This script is meant to be called by the "script" step defined in
 # .travis.yml.
 
 check_error()

.travis.yml

@@ -3,12 +3,27 @@ language: python
 dist: xenial
 
 matrix:
-  fast_finish: true 
+  fast_finish: true
   include:
 
     # Here you can add or remove specific builds, and Python versions. You
     # should currently be able to use Python 2.6, 2.7, or 3.3 or later.
 
+    - stage: 'docs building'
+      env: TEST_SUITE=docs
+      python: '3.7'
+      cache: pip
+      after_success:
+        #test the docs
+      deploy:
+        provider: pages
+        skip_cleanup: true
+        keep_history: true
+        github_token: $token # set in the Travis dashboard
+        local_dir: docs
+        on:
+          branch: master
+      if: branch = master
     - stage: 'style checks'
       python: '2.7.15'
       language: python
@@ -24,6 +39,7 @@ matrix:
 
 
 stages:
+  - 'docs building'
   - 'style checks'
   - 'unit tests'
 

PyRDF/CallableGenerator.py

@@ -2,36 +2,28 @@ class CallableGenerator(object):
     """
     Class that generates a callable to parse a PyRDF graph.
 
-    Attributes
-    ----------
-    head_node
-        Head node of a PyRDF graph.
+    Attributes:
+        head_node: Head node of a PyRDF graph.
     """
     def __init__(self, head_node):
         """
         Creates a new `CallableGenerator`.
 
-        Parameters
-        ----------
-        head_node
-            Head node of a PyRDF graph.
+        Args:
+            head_node: Head node of a PyRDF graph.
         """
         self.head_node = head_node
 
     def get_action_nodes(self, node_py=None):
         """
         Recurses through PyRDF graph and collects the PyRDF node objects.
 
-        Parameters
-        ----------
-        node_py (optional)
-            The current state's PyRDF node. If `None`,
-            it takes the value of `self.head_node`.
+        Args:
+            node_py (optional): The current state's PyRDF node. If `None`, it
+                takes the value of `self.head_node`.
 
-        Returns
-        -------
-        list
-            A list of the action nodes of the graph in DFS order, which
+        Returns:
+            list: A list of the action nodes of the graph in DFS order, which
             coincides with the order of execution in the callable function.
         """
         return_nodes = []
@@ -58,13 +50,10 @@ def get_callable(self):
         """
         Converts a given graph into a callable and returns the same.
 
-        Returns
-        -------
-        function
-            The callable that takes in a PyROOT
-            RDataFrame object and executes all
-            operations from the PyRDF graph on it
-            recursively.
+        Returns:
+            function: The callable that takes in a PyROOT RDataFrame object
+            and executes all operations from the PyRDF graph
+            on it, recursively.
         """
         # Prune the graph to check user references
         self.head_node.graph_prune()
@@ -74,21 +63,15 @@ def mapper(node_cpp, node_py=None):
             The callable that recurses through the PyRDF nodes and executes
             operations from a starting (PyROOT) RDF node.
 
-            Parameters
-            ----------
-            node_cpp
-                The current state's ROOT CPP node. Initially
-                this should be given in as a PyROOT RDataFrame object.
-
-            node_py (optional)
-                The current state's PyRDF node. If `None`,
-                it takes the value of `self.head_node`.
-
-            Returns
-            -------
-            list
-                A list of RResultPtr objects in DFS order
-                of their corresponding actions in the graph.
+            Args:
+                node_cpp: The current state's ROOT CPP node. Initially this
+                    should be given in as a PyROOT RDataFrame object.
+                node_py (optional): The current state's PyRDF node. If `None`,
+                    it takes the value of `self.head_node`.
+
+            Returns:
+                list: A list of :obj:`ROOT.RResultPtr` objects in DFS order of
+                their corresponding actions in the graph.
             """
             return_vals = []
 

PyRDF/Node.py

@@ -8,59 +8,49 @@ class Node(object):
     houses an operation and has references to children nodes.
     For details on the types of operations supported, try :
 
-    import PyRDF
-    PyRDF.use(...) # Choose your backend
-    print(PyRDF.current_backend.supported_operations)
-
-    Attributes
-    ----------
-    get_head : function
-        A lambda function that returns the head
-        node of the current graph.
-
-    operation
-        The operation that this Node represents. This
-        could be `None`.
-
-    children
-        A list of `Node` objects which represent the
-        children nodes connected to the current node.
-
-    _new_op_name
-        The name of the new incoming operation of the next child, which is the
-        last child node among the current node's children.
-
-    value
-        The computed value after executing the operation in
-        the current node for a particular PyRDF graph. This
-        is permanently `None` for transformation nodes and
-        the action nodes get a `RResultPtr` after event-loop
-        execution.
-
-    pyroot_node
-        Reference to the PyROOT object that implements the
-        functionality of this node on the cpp side.
-
-    has_user_references
-        A flag to check whether the node has direct user references, that is
-        if it is assigned to a variable. Default value is `True`, turns to
-        `False` if the proxy that wraps the node gets garbage collected by
-        Python.
+    Example::
+
+        import PyRDF
+        PyRDF.use(...) # Choose your backend
+        print(PyRDF.current_backend.supported_operations)
+
+    Attributes:
+        get_head (function): A lambda function that returns the head node of
+            the current graph.
+
+        operation: The operation that this Node represents.
+            This could be :obj:`None`.
+
+        children (list): A list of :obj:`PyRDF.Node` objects which represent
+            the children nodes connected to the current node.
+
+        _new_op_name (str): The name of the new incoming operation of the next
+            child, which is the last child node among the current node's
+            children.
+
+        value: The computed value after executing the operation in the current
+            node for a particular PyRDF graph. This is permanently :obj:`None`
+            for transformation nodes and the action nodes get a
+            :obj:`ROOT.RResultPtr` after event-loop execution.
+
+        pyroot_node: Reference to the PyROOT object that implements the
+            functionality of this node on the cpp side.
+
+        has_user_references (bool): A flag to check whether the node has
+            direct user references, that is if it is assigned to a variable.
+            Default value is :obj:`True`, turns to :obj:`False` if the proxy
+            that wraps the node gets garbage collected by Python.
     """
     def __init__(self, get_head, operation, *args):
         """
-        Creates a new `Node` based on the 'operation'.
-
-        Parameters
-        ----------
-        get_head : function
-            A lambda function that returns the head
-            node of the current graph. This value
-            could be `None`.
-
-        operation : PyRDF.Operation.Operation
-            The operation that this Node represents. This
-            could be `None`.
+        Creates a new node based on the operation passed as argument.
+
+        Args:
+            get_head (function): A lambda function that returns the head node
+                of the current graph. This value could be `None`.
+
+            operation (PyRDF.Operation.Operation): The operation that this Node
+                represents. This could be :obj:`None`.
         """
         if get_head is None:
             # Function to get 'head' Node
@@ -80,10 +70,8 @@ def __getstate__(self):
         Converts the state of the current node
         to a Python dictionary.
 
-        Returns
-        -------
-        dictionary
-            A dictionary that stores all instance variables
+        Returns:
+            dictionary: A dictionary that stores all instance variables
             that represent the current PyRDF node.
 
         """
@@ -100,11 +88,9 @@ def __setstate__(self, state):
         Retrieves the state dictionary of the current
         node and sets the instance variables.
 
-        Parameters
-        ----------
-        state : dictionary
-            This is the state dictionary that needs to
-            be converted to a `Node` object.
+        Args:
+            state (dict): This is the state dictionary that needs to be
+                converted to a `Node` object.
 
         """
         self.children = state['children']
@@ -120,11 +106,9 @@ def is_prunable(self):
         Checks whether the current node can be pruned from the computational
         graph.
 
-        Returns
-        -------
-        bool
-            True if the node has no children and no user references or its
-            value has already been computed, False otherwise.
+        Returns:
+            bool: True if the node has no children and no user references or
+            its value has already been computed, False otherwise.
         """
         if not self.children:
             # Every pruning condition is written on a separate line
@@ -149,17 +133,13 @@ def graph_prune(self):
         application does not hold any reference to it. The children of the
         current node will get recursively pruned.
 
-        Returns
-        -------
-        bool
-            True if the current node has to be pruned, False otherwise.
-
+        Returns:
+            bool: True if the current node has to be pruned, False otherwise.
         """
         children = []
 
         for n in self.children:
             # Select children based on pruning condition
-
             if not n.graph_prune():
                 children.append(n)