Update Python versions in CONTRIBUTING.rst (#16)

Unless the world really needs to, this package will
only support Python 3.X versions.

Author: ljvmiranda921

AUTHORS.rst

@@ -5,9 +5,12 @@ Credits
 Development Lead
 ----------------
 
-* Lester James V. Miranda <ljvmiranda@gmail.com>
+* Lester James V. Miranda <ljvmiranda@gmail.com> 
 
 Contributors
 ------------
 
-None yet. Why not be the first?
+* `@Carl-K`_
+
+
+.. _`@Carl-K`: https://github.com/Carl-K

CONTRIBUTING.rst

@@ -102,7 +102,7 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check
+3. The pull request should work for Python 3.4, 3.5, and above. Check
    https://travis-ci.org/ljvmiranda921/pyswarms/pull_requests
    and make sure that the tests pass for all supported Python versions.
 

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.
@@ -52,26 +52,25 @@ To use PySwarms in your project,
 
 .. code-block:: python
 
-    import pyswarms
+    import pyswarms as ps
 
 Suppose you want to find the minima of :math:`f(x) = x^2` using global best PSO, simply import the 
 built-in sphere function, :code:`pyswarms.utils.functions.sphere_func()`, and the necessary optimizer:
 
 .. code-block:: python
 
-    from pyswarms.single import GBestPSO
+    import pyswarms as ps
     from pyswarms.utils.functions import sphere_func
 
     # Set-up hyperparameters
     options = {'c1': 0.5, 'c2': 0.3, 'm':0.9}
 
     # Call instance of PSO
-    optimizer = GBestPSO(n_particles=10, dims=2, **options)
+    optimizer = ps.GBestPSO(n_particles=10, dims=2, **options)
 
     # Perform optimization
     stats = optimizer.optimize(sphere_func, iters=100)
 
-More examples can be seen in the :code:`./examples` folder.
 
 Credits
 ---------

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

@@ -0,0 +1,19 @@
+pyswarms.base package
+=====================
+
+.. automodule:: pyswarms.base
+
+
+Submodules
+----------
+
+pyswarms.base.bs module
+------------------------
+
+.. automodule:: pyswarms.base.bs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :special-members: __init__
+

docs/api/pyswarms.rst

@@ -0,0 +1,30 @@
+PySwarms package
+=================
+
+.. automodule:: pyswarms
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Base Classes
+------------
+
+.. toctree::
+
+   pyswarms.base
+
+
+Optimizers
+-----------
+
+.. toctree::
+
+   pyswarms.single
+
+
+Utilities
+----------
+
+.. toctree::
+
+   pyswarms.utils.functions

docs/api/pyswarms.single.rst

@@ -0,0 +1,26 @@
+pyswarms.single package
+=======================
+
+.. automodule:: pyswarms.single
+
+Submodules
+----------
+
+pyswarms.single.gb module
+--------------------------
+
+.. automodule:: pyswarms.single.gb
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+pyswarms.single.lb module
+--------------------------
+
+.. automodule:: pyswarms.single.lb
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :special-members: __init__

docs/api/pyswarms.utils.functions.rst

@@ -0,0 +1,19 @@
+pyswarms.utils.functions package
+================================
+
+.. automodule:: pyswarms.utils.functions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+pyswarms.utils.functions.single_obj module
+-------------------------------------------
+
+.. automodule:: pyswarms.utils.functions.single_obj
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members:

docs/conf.py

@@ -23,13 +23,14 @@
 #sys.path.insert(0, os.path.abspath('.'))
 
 # Get the project root dir, which is the parent dir of this
-cwd = os.getcwd()
-project_root = os.path.dirname(cwd)
+#cwd = os.getcwd()
+#project_root = os.path.dirname(cwd)
 
 # Insert the project root dir as the first element in the PYTHONPATH.
 # This lets us ensure that the source package is imported, and that its
 # version is used.
-sys.path.insert(0, project_root)
+#sys.path.insert(0, project_root)
+sys.path.insert(0, os.path.abspath('../'))
 
 import pyswarms
 
@@ -40,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']
+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']
@@ -144,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.
@@ -195,7 +202,7 @@
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
+    'papersize': 'a4paper',
 
     # The font size ('10pt', '11pt' or '12pt').
     #'pointsize': '10pt',
@@ -258,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.

docs/index.rst

@@ -5,15 +5,20 @@ Contents:
 
 .. toctree::
    :maxdepth: 2
+   :caption: General
 
    readme
    installation
-   usage
-   modules
-   contributing
    authors
    history
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer's Guide
+
+   contributing
+   API Documentation <api/pyswarms>
+
 Indices and tables
 ==================
 

docs/usage.rst

@@ -2,6 +2,27 @@
 Usage
 =====
 
-To use PySwarms in a project::
+To use PySwarms in your project,
 
-    import pyswarms
+.. code-block:: python
+
+    import pyswarms as ps
+
+Optimizing a function
+----------------------
+Suppose you want to find the minima of :math:`f(x) = x^2` using global best PSO, simply import the 
+built-in sphere function, :code:`pyswarms.utils.functions.sphere_func()`, and the necessary optimizer:
+
+.. code-block:: python
+
+    import pyswarms as ps
+    from pyswarms.utils.functions import sphere_func
+
+    # Set-up hyperparameters
+    options = {'c1': 0.5, 'c2': 0.3, 'm':0.9}
+
+    # Call instance of PSO
+    optimizer = ps.GBestPSO(n_particles=10, dims=2, **options)
+
+    # Perform optimization
+    stats = optimizer.optimize(sphere_func, iters=100)

pyswarms/__init__.py

@@ -1,7 +1,15 @@
 # -*- coding: utf-8 -*-
 
-"""Top-level package for PySwarms."""
+"""
+Particle Swarm Optimization (PSO) toolkit
+=========================================
+PySwarms is a particle swarm optimization (PSO) toolkit that enables
+researchers to test variants of the PSO technique in different contexts.
+Users can define their own function, or use one of the benchmark functions
+in the library. It is built on top of :code:`numpy` and :code:`scipy`, and
+is very extensible to accommodate other PSO variations.
+"""
 
 __author__ = """Lester James V. Miranda"""
 __email__ = 'ljvmiranda@gmail.com'
-__version__ = '0.1.0'
+__version__ = '0.1.1'

pyswarms/base/__init__.py

@@ -1,3 +1,8 @@
-""" Base package for `pyswarms` """
+"""
+The :mod:`pyswarms.base` module implements base
+swarm classes to implement variants of particle swarm optimization.
+"""
 
-from .bs import SwarmBase
+from .bs import SwarmBase
+
+__all__ = ["SwarmBase"]