Standardise

.gitlab-ci.yml

+# This build file is defined in two parts: 1) a generic set of instructions you
+# probably **don't** need to change and 2) a part you may have to tune to your
+# project. It heavily uses template features from YAML to help you in only
+# changing a minimal part of it and avoid code duplication to a maximum while
+# still providing a nice pipeline display on your package.
+
+
+# 1) Generic instructions (only change if you know what you're doing)
+# -------------------------------------------------------------------
+
+# Definition of our build pipeline
+stages:
+  - build
+  - test
+  - docs
+  - wheels
+
+
+# Global variables
+variables:
+  CONDA_PREFIX: env
+
+
+# Template for the build stage
+# Needs to run on all supported architectures, platforms and python versions
+.build_template: &build_job
+  stage: build
+  before_script:
+    - git clean -ffdx
+    - curl --silent https://gitlab.idiap.ch/bob/bob/snippets/7/raw | tr -d '\r' > bootstrap-conda.sh
+    - chmod 755 ./bootstrap-conda.sh
+    - ./bootstrap-conda.sh ${CONDA_FOLDER} ${PYTHON_VER} ${CONDA_PREFIX}
+  variables: &build_variables
+    BOB_DOCUMENTATION_SERVER: "http://www.idiap.ch/software/bob/docs/latest/bob/%s/master/"
+  script:
+    - ./bin/buildout
+    - if [ -x ./bin/bob_dbmanage.py ]; then ./bin/bob_dbmanage.py all download --force; fi
+    - ./bin/sphinx-build doc sphinx
+    - ./bin/python setup.py bdist_wheel --python-tag ${WHEEL_TAG}
+  after_script:
+    - rm -rf ${CONDA_PREFIX}
+  artifacts:
+    expire_in: 1 day
+    paths:
+      - bootstrap-conda.sh
+      - dist/
+      - sphinx/
+
+
+# Template for building on a Linux machine
+.build_linux_template: &linux_build_job
+  <<: *build_job
+  variables: &linux_build_variables
+    <<: *build_variables
+    CONDA_FOLDER: "/local/conda"
+    CFLAGS: "-D_GLIBCXX_USE_CXX11_ABI=0 -coverage"
+    CXXFLAGS: "-D_GLIBCXX_USE_CXX11_ABI=0 -coverage"
+
+
+# Template for building on a Mac OSX machine
+.build_mac_template: &macosx_build_job
+  <<: *build_job
+  variables: &macosx_build_variables
+    <<: *build_variables
+    CONDA_FOLDER: "/opt/conda"
+    MACOSX_DEPLOYMENT_TARGET: "10.9"
+    CFLAGS: "-pthread -coverage"
+    CXXFLAGS: "-pthread -coverage"
+    LDFLAGS: "-lpthread"
+
+
+# Template for the test stage - re-install from uploaded wheels
+# Needs to run on all supported architectures, platforms and python versions
+.test_template: &test_job
+  stage: test
+  before_script:
+    - ./bootstrap-conda.sh ${CONDA_FOLDER} ${PYTHON_VER} ${CONDA_PREFIX}
+    - source ${CONDA_FOLDER}/bin/activate ${CONDA_PREFIX}
+    - pip install --use-wheel --no-index --pre dist/*.whl
+  script:
+    - cd ${CONDA_PREFIX}
+    - python -c "from ${CI_PROJECT_NAME} import get_config; print(get_config())"
+    - coverage run --source=${CI_PROJECT_NAME} ./bin/nosetests -sv ${CI_PROJECT_NAME}
+    - coverage report
+    - sphinx-build -b doctest ../doc ../sphinx
+  after_script:
+    - rm -rf ${CONDA_PREFIX}
+
+
+# Template for the wheel uploading stage
+# Needs to run against one combination of python 2.x and 3.x if it is a python
+# only package, otherwise, needs to run in both pythons to all supported
+# architectures (Linux and Mac OSX 64-bit)
+.wheels_template: &wheels_job
+  stage: wheels
+  only:
+    - master
+    - tags
+  before_script:
+    - curl --silent https://gitlab.idiap.ch/bob/bob/snippets/8/raw | tr -d '\r' > upload-wheel.sh
+    - chmod 755 upload-wheel.sh
+  script:
+    - ./upload-wheel.sh
+
+
+# Template for (latest) documentation upload stage
+# Only one real job needs to do this
+.docs_template: &docs_job
+  stage: docs
+  only:
+    - master
+  before_script:
+    - curl --silent https://gitlab.idiap.ch/bob/bob/snippets/9/raw | tr -d '\r' > upload-sphinx.sh
+    - chmod 755 upload-sphinx.sh
+  script:
+    - ./upload-sphinx.sh
+
+
+# 2) Package specific instructions (you may tune this if needed)
+# --------------------------------------------------------------
+
+# Linux + Python 2.7: Builds, tests, uploads wheel
+build_linux_27:
+  <<: *linux_build_job
+  variables: &linux_27_build_variables
+    <<: *linux_build_variables
+    PYTHON_VER: "2.7"
+    WHEEL_TAG: "py27"
+  tags:
+    - conda-linux
+
+test_linux_27:
+  <<: *test_job
+  variables: *linux_27_build_variables
+  dependencies:
+    - build_linux_27
+  tags:
+    - conda-linux
+
+wheels_linux_27:
+  <<: *wheels_job
+  dependencies:
+    - build_linux_27
+  tags:
+    - conda-linux
+
+
+# Linux + Python 3.4: Builds and tests
+build_linux_34:
+  <<: *linux_build_job
+  variables: &linux_34_build_variables
+    <<: *linux_build_variables
+    PYTHON_VER: "3.4"
+    WHEEL_TAG: "py3"
+  tags:
+    - conda-linux
+
+test_linux_34:
+  <<: *test_job
+  variables: *linux_34_build_variables
+  dependencies:
+    - build_linux_34
+  tags:
+    - conda-linux
+
+
+# Linux + Python 3.5: Builds, tests, uploads wheel
+build_linux_35:
+  <<: *linux_build_job
+  variables: &linux_35_build_variables
+    <<: *linux_build_variables
+    PYTHON_VER: "3.5"
+    WHEEL_TAG: "py3"
+  tags:
+    - conda-linux
+
+test_linux_35:
+  <<: *test_job
+  variables: *linux_35_build_variables
+  dependencies:
+    - build_linux_35
+  tags:
+    - conda-linux
+
+wheels_linux_35:
+  <<: *wheels_job
+  dependencies:
+    - build_linux_35
+  tags:
+    - conda-linux
+
+docs_linux_35:
+  <<: *docs_job
+  dependencies:
+    - build_linux_35
+  tags:
+    - conda-linux
+
+
+# Mac OSX + Python 2.7: Builds and tests
+build_macosx_27:
+  <<: *macosx_build_job
+  variables: &macosx_27_build_variables
+    <<: *macosx_build_variables
+    PYTHON_VER: "2.7"
+    WHEEL_TAG: "py27"
+  tags:
+    - conda-macosx
+
+test_macosx_27:
+  <<: *test_job
+  variables: *macosx_27_build_variables
+  dependencies:
+    - build_macosx_27
+  tags:
+    - conda-macosx
+
+
+# Mac OSX + Python 3.4: Builds and tests
+build_macosx_34:
+  <<: *macosx_build_job
+  variables: &macosx_34_build_variables
+    <<: *macosx_build_variables
+    PYTHON_VER: "3.4"
+    WHEEL_TAG: "py3"
+  tags:
+    - conda-macosx
+
+test_macosx_34:
+  <<: *test_job
+  variables: *macosx_34_build_variables
+  dependencies:
+    - build_macosx_34
+  tags:
+    - conda-macosx
+
+
+# Mac OSX + Python 3.5: Builds and tests
+build_macosx_35:
+  <<: *macosx_build_job
+  variables: &macosx_35_build_variables
+    <<: *macosx_build_variables
+    PYTHON_VER: "3.5"
+    WHEEL_TAG: "py3"
+  tags:
+    - conda-macosx
+
+test_macosx_35:
+  <<: *test_job
+  variables: *macosx_35_build_variables
+  dependencies:
+    - build_macosx_35
+  tags:
+    - conda-macosx
\ No newline at end of file

.travis.yml

-language: python
-matrix:
-  include:
-  - python: 2.7
-    env:
-    - secure: CchM+63gNGQp44wkG/vzx52uHg6R2XrFaV9P5Anid88h2wiqQi8N6UYD7oF7cNMc+e/wSaa4sv802blsk+8HUv6e6RUIWHqXsDQM9iXWemAAwrT8zvL+Nc/CtTKWGBhVn+rtwr7eEZRcAUii+obDSxc5R7lJGMJzqxO5x6tl77LDEHNcSguF58RJQOifcabThYT7VnZkV4DqGzfaG5ngZwcIGF34zlkOTvtVwnmfM7EdPjzQitKlurM1w2ViyiClby9OO/nAk7T7HgqT6ZkzW0G9exdgeztTzqjtS9DL4FIDdm17cCDWEdLeCgXBO3DKJ9J/XNS0ND7WQooMSFSf8dLQTYMfSDP1AZxPeyb260hIVwMSyJxeS6l8HnAphuBuOo/f8gNteWNxShxcAC8uiVm/EcCLmrwLWSmfPjGyje0QRaJzQ45kQXEf25lm1uPlH3cyYCIn52Y2yP7vwDk1JIbk9G6E6oIZjRq4myZUJCfOzyATZUlZ/EzzZS4fnSxGc9YGOERxAc1E8VcEAq+WbGuNmYJidOGRm5NKzL7rvXWAkfvbSDdNZPZPETAPSKFAqLyYZbCAKzefAQRTyA6CQE8d9HBkEr5iNevlxbuVBF70cUcnsTyLaFpA3t+XvbiR3FhOGjLrfJ/yiZjJihl7bgYimIlntI8vAasgjUxBZ3Q=
-    - secure: j4yg2mFK9jAzgB+aGJj9ieSGYq0iJBTopUSznd9HwT0xAwXGFkOhV2D8t+a0Ww1tuD8eYHKVfLBCMXV9ahelFbIBOM4ajMRsSJf8YcxdqaGFU/4BoKJd6G6chpz3HtScB/VGGO5uRLIqDQWgii6+pEAk3uj5csLp0amL0LCWdhCYHrh94NbeVsJvxPN4LTOTChKZjbo3yhUCPWuKTvbhPteE0NGuf1Ko6NqxaCzT9Iq11YbdNSmJmZnNbOqLkvFFQLdtzV3NXHFstep1YCRcDHLz/wNxkvh9iROUmrdT1b0D8IxexmwFMfVt8GsnrTRAe9jS7mQq7ccE90cJU2nHwh+pzAKyg/wmDdRBkDP08flEZprCUvYWGwoVv5E7GUGxG0voVdLJd2CD2NUHsvyvLZqY1R0EcRvc61aeVY9p/S/r2JzlzZjJTrdh3TUw0OcQ4cymM0VPXKU7N+x89KOhJMbGNwxibd4BtILY5A52nuTy+u1uiiUDFh96rFd3bl3ZwwmnY/CaOmclNILTpa9USsZGngn3Q+juoA8HPKZ7murNl+/mZpopb6tBqQNys5y9AHpX/wdWb36cupmysccmO54cmvfVIuVnOgxFMxlZpBhI4B/TGEeioED6gwJs092TaXBKs2eR5fVuwevZISQOpoH07cmp2bN7fwXQpgdVU6I=
-    - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
-    - BOB_UPLOAD_WHEEL="--universal"
-  - python: 3.3
-  - python: 3.4
-  - python: 3.5
-before_install:
-# - sudo add-apt-repository -y ppa:biometrics/bob
-- sudo apt-get update -qq
-- sudo apt-get install -qq --force-yes dvipng texlive-latex-base texlive-latex-extra texlive-math-extra texlive-latex-recommended texlive-fonts-recommended
-- pip install --upgrade pip
-- pip install --find-links https://www.idiap.ch/software/bob/wheels/travis/ --use-wheel sphinx nose numpy scipy matplotlib coverage
-- pip install --find-links https://www.idiap.ch/software/bob/wheels/travis/ --use-wheel --pre -r requirements.txt coveralls
-install:
-- python bootstrap-buildout.py
-- ./bin/buildout buildout:develop=. buildout:extensions=bob.buildout buildout:auto-checkout=
-script:
-# - ./bin/python -c 'import pkg_resources; from bob.bio.base import get_config; print(get_config())'
-- ./bin/coverage run --source=gridtk ./bin/nosetests -sv
-- ./bin/sphinx-build -b doctest doc sphinx
-- ./bin/sphinx-build -b html doc sphinx
-after_success:
-- coveralls
-- wget https://raw.githubusercontent.com/bioidiap/bob.extension/master/scripts/upload-{sphinx,wheel}.sh
-- chmod a+x upload-sphinx.sh upload-wheel.sh
-- ./upload-sphinx.sh
-- ./upload-wheel.sh

MANIFEST.in

-include README.rst bootstrap-buildout.py buildout.cfg version.txt
+include README.rst bootstrap-buildout.py buildout.cfg develop.cfg version.txt
 recursive-include doc *.rst
 recursive-include gridtk *.sh

bootstrap-buildout.py

@@ -25,7 +25,10 @@ import tempfile
 
 from optparse import OptionParser
 
-tmpeggs = tempfile.mkdtemp()
+__version__ = '2015-07-01'
+# See zc.buildout's changelog if this version is up to date.
+
+tmpeggs = tempfile.mkdtemp(prefix='bootstrap-')
 
 usage = '''\
 [DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
@@ -40,8 +43,9 @@ this script from going over the network.
 '''
 
 parser = OptionParser(usage=usage)
-parser.add_option("-v", "--version", help="use a specific zc.buildout version")
-
+parser.add_option("--version",
+                  action="store_true", default=False,
+                  help=("Return bootstrap.py version."))
 parser.add_option("-t", "--accept-buildout-test-releases",
                   dest='accept_buildout_test_releases',
                   action="store_true", default=False,
@@ -59,25 +63,33 @@ parser.add_option("-f", "--find-links",
 parser.add_option("--allow-site-packages",
                   action="store_true", default=False,
                   help=("Let bootstrap.py use existing site packages"))
+parser.add_option("--buildout-version",
+                  help="Use a specific zc.buildout version")
 parser.add_option("--setuptools-version",
-                  help="use a specific setuptools version")
-
+                  help="Use a specific setuptools version")
+parser.add_option("--setuptools-to-dir",
+                  help=("Allow for re-use of existing directory of "
+                        "setuptools versions"))
 
 options, args = parser.parse_args()
+if options.version:
+    print("bootstrap.py version %s" % __version__)
+    sys.exit(0)
+
 
 ######################################################################
 # load/install setuptools
 
 try:
-    if options.allow_site_packages:
-        import setuptools
-        import pkg_resources
     from urllib.request import urlopen
 except ImportError:
     from urllib2 import urlopen
 
 ez = {}
-exec(urlopen('https://bootstrap.pypa.io/ez_setup.py').read(), ez)
+if os.path.exists('ez_setup.py'):
+    exec(open('ez_setup.py').read(), ez)
+else:
+    exec(urlopen('https://bootstrap.pypa.io/ez_setup.py').read(), ez)
 
 if not options.allow_site_packages:
     # ez_setup imports site, which adds site packages
@@ -88,12 +100,19 @@ if not options.allow_site_packages:
     # We can't remove these reliably
     if hasattr(site, 'getsitepackages'):
         for sitepackage_path in site.getsitepackages():
-            sys.path[:] = [x for x in sys.path if sitepackage_path not in x]
+            # Strip all site-packages directories from sys.path that
+            # are not sys.prefix; this is because on Windows
+            # sys.prefix is a site-package directory.
+            if sitepackage_path != sys.prefix:
+                sys.path[:] = [x for x in sys.path
+                               if sitepackage_path not in x]
 
 setup_args = dict(to_dir=tmpeggs, download_delay=0)
 
 if options.setuptools_version is not None:
     setup_args['version'] = options.setuptools_version
+if options.setuptools_to_dir is not None:
+    setup_args['to_dir'] = options.setuptools_to_dir
 
 ez['use_setuptools'](**setup_args)
 import setuptools
@@ -110,7 +129,12 @@ for path in sys.path:
 
 ws = pkg_resources.working_set
 
+setuptools_path = ws.find(
+    pkg_resources.Requirement.parse('setuptools')).location
+
+# Fix sys.path here as easy_install.pth added before PYTHONPATH
 cmd = [sys.executable, '-c',
+       'import sys; sys.path[0:0] = [%r]; ' % setuptools_path +
        'from setuptools.command.easy_install import main; main()',
        '-mZqNxd', tmpeggs]
 
@@ -123,11 +147,8 @@ find_links = os.environ.get(
 if find_links:
     cmd.extend(['-f', find_links])
 
-setuptools_path = ws.find(
-    pkg_resources.Requirement.parse('setuptools')).location
-
 requirement = 'zc.buildout'
-version = options.version
+version = options.buildout_version
 if version is None and not options.accept_buildout_test_releases:
     # Figure out the most recent final version of zc.buildout.
     import setuptools.package_index
@@ -167,7 +188,7 @@ if version:
 cmd.append(requirement)
 
 import subprocess
-if subprocess.call(cmd, env=dict(os.environ, PYTHONPATH=setuptools_path)) != 0:
+if subprocess.call(cmd) != 0:
     raise Exception(
         "Failed to execute command:\n%s" % repr(cmd)[1:-1])
 

buildout.cfg

+; vim: set fileencoding=utf-8 :
+; Tue 16 Aug 16:07:37 CEST 2016
+
 [buildout]
 parts = scripts
 develop = .
-
-; required packages: our package
-; optional package: ipdb (for debugging)
 eggs = gridtk
-        ipdb
+extensions = bob.buildout
+newest = false
+verbose = true
 
 [scripts]
 recipe = bob.buildout:scripts
-
+dependent-scripts = true
\ No newline at end of file

doc/conf.py

 #!/usr/bin/env python
 # vim: set fileencoding=utf-8 :
-# Manuel Guenther <manuel.guenther@idiap.ch>
-# Tue Nov  4 18:34:42 CET 2014
-#
-# Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
 
 import os
 import sys
@@ -11,33 +7,40 @@ import glob
 import pkg_resources
 
 
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.3'
 
 # 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.todo',
     'sphinx.ext.coverage',
-  'sphinx.ext.pngmath',
     'sphinx.ext.ifconfig',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
+    'sphinx.ext.graphviz',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
     ]
 
-# The viewcode extension appeared only on Sphinx >= 1.0.0
 import sphinx
-if sphinx.__version__ >= "1.0":
-  extensions.append('sphinx.ext.viewcode')
+if sphinx.__version__ >= "1.4.1":
+    extensions.append('sphinx.ext.imgmath')
+else:
+    extensions.append('sphinx.ext.pngmath')
+
+# Always includes todos
+todo_include_todos = True
+
+# Generates auto-summary automatically
+autosummary_generate = True
+
+# Create numbers on figures with captions
+numfig = True
 
 # If we are on OSX, the 'dvipng' path maybe different
 dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
@@ -56,12 +59,12 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'GridTk'
+project = u'gridtk'
 import time
 copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
 
 # Grab the setup entry
-distribution = pkg_resources.require('gridtk')[0]
+distribution = pkg_resources.require(project)[0]
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -84,7 +87,7 @@ release = distribution.version
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['links.rst']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -106,12 +109,18 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# Some variables which are useful for generated material
+project_variable = project.replace('.', '_')
+short_description = u'Parallel Job Manager'
+owner = [u'Idiap Research Institute']
+
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+import sphinx_rtd_theme
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -119,28 +128,28 @@ html_theme = 'default'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+#html_short_title = project_variable
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = 'img/logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = 'img/favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -184,68 +193,48 @@ html_theme = 'default'
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'gridtk_doc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+htmlhelp_basename = project_variable + u'_doc'
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'gridtk.tex', u'Grid TookKit Documentation',
-   u'Idiap Research Institute', 'manual'),
-]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
+# -- Post configuration --------------------------------------------------------
 
 # Included after all input documents
 rst_epilog = """
-.. Some variables
-.. |project| replace:: GridTk
-.. |current-year| date:: %Y
-"""
-
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    ('index', 'idiap', u'GridTk Documentation',
-     [u'Idiap Research Institute'], 1)
-]
+.. |project| replace:: Bob
+.. |version| replace:: %s
+.. |current-year| date:: %%Y
+""" % (version,)
 
 # Default processing flags for sphinx
-autoclass_content = 'both'
+autoclass_content = 'class'
 autodoc_member_order = 'bysource'
-autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
+autodoc_default_flags = [
+  'members',
+  'undoc-members',
+  'inherited-members',
+  'show-inheritance',
+  ]
 
+# For inter-documentation mapping:
+from bob.extension.utils import link_documentation
+intersphinx_mapping = link_documentation()
+
+# We want to remove all private (i.e. _. or __.__) members
+# that are not in the list of accepted functions
+accepted_private_functions = ['__array__']
+
+def member_function_test(app, what, name, obj, skip, options):
+  # test if we have a private function
+  if len(name) > 1 and name[0] == '_':
+    # test if this private function should be allowed
+    if name not in accepted_private_functions:
+      # omit privat functions that are not in the list of accepted private functions
+      return skip
+    else:
+      # test if the method is documented
+      if not hasattr(obj, '__doc__') or not obj.__doc__:
+        return skip
+  return False
 
 def setup(app):
-  pass
+  app.connect('autodoc-skip-member', member_function_test)

doc/index.rst

@@ -4,15 +4,18 @@
 
 .. _gridtk:
 
-Parallel Execution of Jobs in the SGE Grid or on a Local Machine
-================================================================
+======================
+ Parallel Job Manager
+======================
 
-The GridTK serves as a tool to submit jobs and keep track of their dependencies and their current statuses.
-These jobs can either be submitted to an SGE grid, or to be run in parallel on the local machine.
+The GridTK serves as a tool to submit jobs and keep track of their dependencies
+and their current statuses. These jobs can either be submitted to an SGE grid,
+or to be run in parallel on the local machine.
 
-There are two main ways to interact with the GridTK.
-The easiest way is surely to use the command line interface, for details please read the :ref:`command_line` section.
-It is also possible to use the GridTK in a program, the developer interface is described in the :ref:`developer` section.
+There are two main ways to interact with the GridTK. The easiest way is surely
+to use the command line interface, for details please read the
+:ref:`command_line` section.  It is also possible to use the GridTK in a
+program, the developer interface is described in the :ref:`developer` section.
 
 
 Contents:
@@ -29,4 +32,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

doc/program.rst

@@ -4,12 +4,13 @@
 
 .. _developer:
 
-=====================
-The GridTk User Guide
-=====================
+=======================
+ The GridTk User Guide
+=======================
 
-The ``gridtk`` framework is a python library to help submitting, tracking and querying SGE.
-Here is quick example on how to use the ``gridtk`` framework to submit a python script:
+The ``gridtk`` framework is a python library to help submitting, tracking and
+querying SGE.  Here is quick example on how to use the ``gridtk`` framework to
+submit a python script:
 
 .. code-block:: python
 
@@ -21,6 +22,7 @@ Here is quick example on how to use the ``gridtk`` framework to submit a python
    command = make_shell(sys.executable, ['myscript.py', '--help'])
    job = manager.submit(command)
 
+
 You can do, programatically, everything you can do with the job manager - just
 browse the help messages and the ``jman`` script for more information.
 

requirements.txt

 sqlalchemy
+bob.extension

setup.cfg

-[build_sphinx]
-source-dir = docs
-build-dir  = sphinx
-all_files  = 1
-
-[upload_sphinx]
-upload-dir = sphinx/html
-

setup.py

@@ -2,27 +2,25 @@ from setuptools import setup, find_packages