Updated documentation (#16)

README.rst

@@ -18,7 +18,7 @@ PySwarms
      :alt: Updates
 
 
-PySwarms is a simple, Python-based, Particle Swarm Optimization (PSO) library. 
+PySwarms is a simple, Python-based, Particle Swarm Optimization (PSO) library.
 
 * Free software: MIT license
 * Documentation: https://pyswarms.readthedocs.io.

docs/_static/theme_load.css

@@ -0,0 +1,17 @@
+.wy-menu-vertical header, .wy-menu-vertical p.caption {
+	color: gold;
+}
+
+.wy-menu-vertical a {
+	color: white;
+}
+
+.wy-side-nav-search 
+{
+	color: #cacaca;
+	background: #074E68
+}
+
+.wy-side-nav-search input[type=text] {
+	border-color: rgba(7, 78, 104, 0.83);
+}

docs/api/pyswarms.base.rst

@@ -2,9 +2,7 @@ pyswarms.base package
 =====================
 
 .. automodule:: pyswarms.base
-   :members:
-   :undoc-members:
-   :show-inheritance:
+
 
 Submodules
 ----------
@@ -16,5 +14,6 @@ pyswarms.base.bs module
    :members:
    :undoc-members:
    :show-inheritance:
-   :special-members:
+   :private-members:
+   :special-members: __init__
 

docs/api/pyswarms.single.rst

@@ -2,9 +2,6 @@ pyswarms.single package
 =======================
 
 .. automodule:: pyswarms.single
-   :members:
-   :undoc-members:
-   :show-inheritance:
 
 Submodules
 ----------
@@ -16,7 +13,7 @@ pyswarms.single.gb module
    :members:
    :undoc-members:
    :show-inheritance:
-   :special-members:
+   :special-members: __init__
 
 pyswarms.single.lb module
 --------------------------
@@ -25,4 +22,5 @@ pyswarms.single.lb module
    :members:
    :undoc-members:
    :show-inheritance:
-   :special-members:
+   :private-members:
+   :special-members: __init__

docs/conf.py

@@ -41,7 +41,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinx.ext.mathjax']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -145,9 +145,15 @@
 # "default.css".
 html_static_path = ['_static']
 
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # overrides for wide tables in RTD theme
+        ],
+    }
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -196,7 +202,7 @@
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
+    'papersize': 'a4paper',
 
     # The font size ('10pt', '11pt' or '12pt').
     #'pointsize': '10pt',
@@ -259,8 +265,8 @@
      u'PySwarms Documentation',
      u'Lester James V. Miranda',
      'pyswarms',
-     'One line description of project.',
-     'Miscellaneous'),
+     'PySwarms is a simple, Python-based, Particle Swarm Optimization (PSO) library.',
+     'Research'),
 ]
 
 # Documents to append as an appendix to all manuals.

pyswarms/__init__.py

@@ -12,4 +12,4 @@
 
 __author__ = """Lester James V. Miranda"""
 __email__ = 'ljvmiranda@gmail.com'
-__version__ = '0.1.0'
+__version__ = '0.1.1'

pyswarms/base/bs.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-""" bs.py: base class for single-objective PSO """
+""" :code:`bs.py`: base class for single-objective PSO """
 
 import numpy as np 
 
@@ -9,49 +9,47 @@ class SwarmBase(object):
     """Base class for single-objective Particle Swarm Optimization 
     implementations.
 
-    Note that all methods here are abstract and raises a 
-    NotImplementedError when not used. When defining your own swarm, 
+    All methods here are abstract and raises a :code:`NotImplementedError` 
+    when not used. When defining your own swarm implementation,
     create another class,
 
     >>> class MySwarm(SwarmBaseClass):
     >>>     def __init__(self):
     >>>        super(MySwarm, self).__init__()
 
-    and define all the necessary methods needed for your 
-    implementation.
+    and define all the necessary methods needed.
 
-    Take note that there is no velocity nor position update in this 
-    base class. This enables this class to accommodate any variation 
-    of the position or velocity update, without enforcing a specific 
-    structure.
-
-    If you wish to pattern your update rules to the original PSO by 
-    Eberhant et al., simply check the global best and local best
+    Take note that there is no velocity nor position update in this
+    base class. This enables this class to accommodate any variation
+    of the position or velocity update, without enforcing a specific
+    structure. As a guide, check the global best and local best
     implementations in this package.
 
-    .. note:: Regarding `**kwargs`, it is highly recommended to include
-        parameters used in position and velocity updates as keyword
-        arguments. For parameters that affect the topology of the swarm,
-        it may be much better to have them as positional arguments.
+    .. note:: Regarding :code:`**kwargs`, it is highly recommended to
+        include parameters used in position and velocity updates as
+        keyword arguments. For parameters that affect the topology of
+        the swarm, it may be much better to have them as positional
+        arguments.
 
     See Also
     --------
-    swarms.standard.pso.GBestPSO: global-best PSO implementation
-    swarms.standard.pso.LBestPSO: local-best PSO implementation
+    :mod:`pyswarms.single.gb`: global-best PSO implementation
+    :mod:`pyswarms.single.lb`: local-best PSO implementation
     """
     def assertions(self):
         """Assertion method to check various inputs.
         
         Raises
         ------
         TypeError
-            When the `bounds` is not of type tuple
+            When the :code:`bounds` is not of type tuple
         IndexError
-            When the `bounds` is not of size 2.
-            When the arrays in `bounds` is not of equal size.
-            When the shape of `bounds` is not the same as `dims`.
+            When the :code:`bounds` is not of size 2.
+            When the arrays in :code:`bounds` is not of equal size.
+            When the shape of :code:`bounds` is not the same as `dims`.
         ValueError
-            When the value of `bounds[1]` is less than `bounds[0]`.
+            When the value of :code:`bounds[1]` is less than
+            :code:`bounds[0]`.
         """
 
         # Check setting of bounds
@@ -70,10 +68,10 @@ def assertions(self):
     def __init__(self, n_particles, dims, bounds=None, **kwargs):
         """Initializes the swarm. 
 
-        Creates a numpy.ndarray of positions depending on the number 
-        of particles needed and the number of dimensions. The initial 
-        positions of the particles are sampled from a uniform 
-        distribution.
+        Creates a :code:`numpy.ndarray` of positions depending on the
+        number of particles needed and the number of dimensions.
+        The initial positions of the particles are sampled from a
+        uniform distribution.
 
         Attributes
         ----------
@@ -84,10 +82,10 @@ def __init__(self, n_particles, dims, bounds=None, **kwargs):
         bounds : tuple of numpy.ndarray
             a tuple of size 2 where the first entry is the minimum bound
             while the second entry is the maximum bound. Each array must
-            be of shape (dims,).
+            be of shape :code:`(dims,)`.
         **kwargs: dict
-            a dictionary containing various kwargs for a specific 
-            optimization technique
+            a dictionary containing various keyword arguments for a
+            specific optimization technique
         """
         # Initialize primary swarm attributes
         self.n_particles = n_particles
@@ -106,7 +104,7 @@ def optimize(self, f, iters, print_step=1, verbose=1):
         """Optimizes the swarm for a number of iterations.
 
         Performs the optimization to evaluate the objective 
-        function `f` for a number of iterations `iter.`
+        function :code:`f` for a number of iterations :code:`iter.`
 
         Parameters
         ----------
@@ -130,18 +128,18 @@ def reset(self):
         """Resets the attributes of the optimizer.
         
         All variables/atributes that will be re-initialized when this
-        method is called should be defined here. Note that this method
+        method is defined here. Note that this method
         can be called twice: (1) during initialization, and (2) when
         this is called from an instance.
 
-        It is recommended to keep the number resettable
+        It is good practice to keep the number of resettable
         attributes at a minimum. This is to prevent spamming the same
         object instance with various swarm definitions.
 
-        Normally, we would like to keep each swarm definitions as atomic
-        as possible, where each type of swarm is contained in its own
-        instance. Thus, the following attributes are the only ones
-        recommended to be resettable:
+        Normally, swarm definitions are as atomic as possible, where
+        each type of swarm is contained in its own instance. Thus, the
+        following attributes are the only ones recommended to be
+        resettable:
             * Swarm position matrix (self.pos)
             * Velocity matrix (self.pos)
             * Best scores and positions (gbest_cost, gbest_pos, etc.)

pyswarms/single/gb.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-""" gb.py: global-best partical swarm optimization algorithm """
+""" gb.py: global-best particle swarm optimization algorithm """
 
 # Import modules
 import numpy as np
@@ -17,8 +17,8 @@ class GBestPSO(SwarmBase):
     star-topology where each particle is attracted to the best 
     performing particle.
 
-    .. note:: This algorithm was adapted from the earlier works of J.
-        Kennedy and R.C. Eberhart in Particle Swarm Optimization [1]_
+    This algorithm was adapted from the earlier works of J. Kennedy and
+    R.C. Eberhart in Particle Swarm Optimization [1]_
 
     .. [1] J. Kennedy and R.C. Eberhart, "Particle Swarm Optimization,"
         Proceedings of the IEEE International Joint Conference on Neural
@@ -45,20 +45,20 @@ def assertions(self):
     def __init__(self, n_particles, dims, bounds=None, **kwargs):
         """Initializes the swarm. 
 
-        Takes the same attributes as SwarmBase, but also
+        Takes the same attributes as :code:`SwarmBase`, but also
         initializes a velocity component by sampling from a random
-        distribution with range [0,1].
+        distribution with range :code:`[0,1]`.
 
         Attributes
         ----------
         n_particles : int
             number of particles in the swarm.
         dims : int
             number of dimensions in the space.
-        bounds : tuple of np.ndarray, optional (default is None)
+        bounds : tuple of np.ndarray, optional (default is :code:`None`)
             a tuple of size 2 where the first entry is the minimum bound
             while the second entry is the maximum bound. Each array must
-            be of shape (dims,).
+            be of shape :code:`(dims,)`.
         **kwargs : dict
             Keyword argument that must contain the following dictionary
             keys:
@@ -80,7 +80,7 @@ def optimize(self, f, iters, print_step=1, verbose=1):
         """Optimizes the swarm for a number of iterations.
 
         Performs the optimization to evaluate the objective
-        function `f` for a number of iterations `iter.`
+        function :code:`f` for a number of iterations :code:`iter.`
 
         Parameters
         ----------
@@ -145,9 +145,9 @@ def reset(self):
     def _update_velocity_position(self):
         """Updates the velocity and position of the swarm.
 
-        Specifically, it updates the attributes self.velocity and
-        self.pos. This function is being called by the
-        self.optimize() method
+        Specifically, it updates the attributes :code:`self.velocity`
+        and :code:`self.pos`. This function is being called by the
+        :code:`self.optimize()` method
         """
         # Define the hyperparameters from kwargs dictionary
         c1, c2, m = self.kwargs['c1'], self.kwargs['c2'], self.kwargs['m']