Commit 34e84eaa authored by eric pellegrini's avatar eric pellegrini
Browse files

Modified and refactored (many) docstrings for not having anymore any

warnings with sphinx
parent cd27c20d
......@@ -8,7 +8,7 @@ MDANSE_API="../MDANSE/Doc/API"
#mkdir ${MDANSE_API}/_static
#mkdir ${MDANSE_API}/_templates
sphinx-apidoc -o ${MDANSE_API} -F --separate -d 5 -H MDANSE -A "G. Goret & E. Pellegrini" -V 1.0 -R 1.0 ../MDANSE
sphinx-apidoc -o ${MDANSE_API} -F --separate -d 5 -H MDANSE -A "G. Goret & E. Pellegrini" -V 1.0 -R 1.0 ../MDANSE ../MDANSE/Externals
cp conf_html.py ${MDANSE_API}/conf.py
......
#MDANSE : Molecular Dynamics Analysis for Neutron Scattering Experiments
#------------------------------------------------------------------------------------------
#Copyright (C)
#2015- Eric C. Pellegrini Institut Laue-Langevin
#BP 156
#6, rue Jules Horowitz
#38042 Grenoble Cedex 9
#France
#pellegrini[at]ill.fr
#goret[at]ill.fr
#aoun[at]ill.fr
#
#This library is free software; you can redistribute it and/or
#modify it under the terms of the GNU Lesser General Public
#License as published by the Free Software Foundation; either
#version 2.1 of the License, or (at your option) any later version.
#
#This library is distributed in the hope that it will be useful,
#but WITHOUT ANY WARRANTY; without even the implied warranty of
#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
#Lesser General Public License for more details.
#
#You should have received a copy of the GNU Lesser General Public
#License along with this library; if not, write to the Free Software
#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
'''
Created on Mar 30, 2015
@author: goret
'''
# import os
# import shutil
# import sys
#
# import MDANSE
# MDANSE_PATH = os.path.abspath('../MDANSE')
# sys.path.append(os.path.dirname(__file__))
#
# 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.append(MDANSE_PATH)
# DOC_PATH = os.path.join(MDANSE_PATH,'Doc')
# if not os.path.exists(DOC_PATH):
# os.makedirs(DOC_PATH)
#
# shutil.copy('mdanse_logo.png',DOC_PATH)
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.0'
# 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.graphviz', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.pngmath']#,'rst2pdf.pdfbuilder']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'MDANSE'
copyright = u'2015, Gael Goret, Bachir Aoun and Eric C. Pellegrini'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'
html_logo = '_static/mdanse_logo.png'
inheritance_graph_attrs = dict(size='""')
inheritance_graph_attrs = dict(rankdir="TB", size='""')
inheritance_node_attrs = dict(color='lightblue', style='filled')
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output ---------------------------------------------------
html_sidebars = {'**': ['localtoc.html','sourcelink.html', 'searchbox.html']}
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "nature"
html_theme_options = {'sidebarwidth':250}#, 'nosidebar':True}
# Output file base name for HTML help builder.
htmlhelp_basename = 'MDANSE_doc'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'MDANSE.tex', u'MDANSE Documentation',
u'Gael Goret \\& Eric C. Pellegrini', 'manual'),
]
pdf_documents = [('index', 'MDANSE', u'MDANSE Documentation', u'Gael Goret & Eric C. Pellegrini'),]
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [('index', 'MDANSE', u'MDANSE Documentation', u'Gael Goret & Eric C. Pellegrini'),]
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [('index', 'MDANSE', u'MDANSE Documentation',u'Gael Goret & Eric C. Pellegrini','MDANSE', 'One line description of project.','Miscellaneous'),]
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_patterns = ['Externals']
members_to_watch = ['class']
def flag_onthefly(app, what, name, obj, options, lines):
from MDANSE import REGISTRY
for kls in REGISTRY["job"].values():
kls.__doc__ += kls.build_doc()
if(what in members_to_watch):
# and modify the docstring so the rendered output is highlights the omission
if lines:
lines.insert(0,'**Description:**\n\n')
lines.insert(0,' .. inheritance-diagram:: %s\n'%name.split('.')[-1])
lines.insert(0,'**inheritance-diagram:**\n\n')
# def setup(app):
#
# app.connect('autodoc-process-docstring', flag_onthefly)
#MDANSE : Molecular Dynamics Analysis for Neutron Scattering Experiments
#------------------------------------------------------------------------------------------
#Copyright (C)
#2015- Eric C. Pellegrini Institut Laue-Langevin
#BP 156
#6, rue Jules Horowitz
#38042 Grenoble Cedex 9
#France
#pellegrini[at]ill.fr
#goret[at]ill.fr
#aoun[at]ill.fr
#
#This library is free software; you can redistribute it and/or
#modify it under the terms of the GNU Lesser General Public
#License as published by the Free Software Foundation; either
#version 2.1 of the License, or (at your option) any later version.
#
#This library is distributed in the hope that it will be useful,
#but WITHOUT ANY WARRANTY; without even the implied warranty of
#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
#Lesser General Public License for more details.
#
#You should have received a copy of the GNU Lesser General Public
#License along with this library; if not, write to the Free Software
#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
'''
Created on Jun 16, 2015
:author: Eric C. Pellegrini
'''
import cPickle
import glob
import optparse
import os
import subprocess
import sys
from MDANSE.Core.Error import Error
from MDANSE import ELEMENTS, PLATFORM, REGISTRY
from MDANSE.Framework.Jobs.JobStatus import JobState
class CommandLineParserError(Error):
pass
class CommandLineParser(optparse.OptionParser):
'''A sublcass of OptionParser.
Creates the MDANSE commad line parser.
'''
def add_mmtk_definition(self, option, opt_str, value, parser):
if len(parser.rargs) != 3:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
from MDANSE.Framework.MMTKDefinitions import MMTK_DEFINITIONS
MMTK_DEFINITIONS.add(*parser.rargs)
MMTK_DEFINITIONS.save()
def check_job(self, option, opt_str, value, parser):
'''Display the jobs list
@param option: the option that triggered the callback.
@type option: optparse.Option instance
@param opt_str: the option string seen on the command line.
@type opt_str: str
@param value: the argument for the option.
@type value: str
@param parser: the MDANSE option parser.
@type parser: instance of MDANSEOptionParser
'''
if len(parser.rargs) != 1:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
basename = parser.rargs[0]
filename = os.path.join(PLATFORM.temporary_files_directory(),basename)
if not os.path.exists(filename):
raise CommandLineParserError("Invalid job name")
# Open the job temporary file
try:
f = open(filename, 'rb')
info = cPickle.load(f)
f.close()
# If the file could not be opened/unpickled for whatever reason, try at the next checkpoint
except:
raise CommandLineParserError("The job %r could not be opened properly." % basename)
# The job file could be opened and unpickled properly
else:
# Check that the unpickled object is a JobStatus object
if not isinstance(info,JobState):
raise CommandLineParserError("Invalid contents for job %r." % basename)
print "Information about %s job:" % basename
for k,v in info.iteritems():
print "%-20s [%s]" % (k,v)
def display_element_info(self, option, opt_str, value, parser):
if len(parser.rargs) != 1:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
element = parser.rargs[0]
try:
print ELEMENTS.info(element)
except ValueError:
raise CommandLineParserError("The entry %r is not registered in the database" % element)
def display_jobs_list(self, option, opt_str, value, parser):
'''Display the jobs list
@param option: the option that triggered the callback.
@type option: optparse.Option instance
@param opt_str: the option string seen on the command line.
@type opt_str: str
@param value: the argument for the option.
@type value: str
@param parser: the MDANSE option parser.
@type parser: instance of MDANSEOptionParser
'''
if len(parser.rargs) != 0:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
jobs = [f for f in glob.glob(os.path.join(PLATFORM.temporary_files_directory(),'*'))]
for j in jobs:
# Open the job temporary file
try:
f = open(j, 'rb')
info = cPickle.load(f)
f.close()
# If the file could not be opened/unpickled for whatever reason, try at the next checkpoint
except:
continue
# The job file could be opened and unpickled properly
else:
# Check that the unpickled object is a JobStatus object
if not isinstance(info,JobState):
continue
print "%-20s [%s]" % (os.path.basename(j),info["state"])
def display_trajectory_contents(self, option, opt_str, value, parser):
'''Displays trajectory contents
@param option: the option that triggered the callback.
@type option: optparse.Option instance
@param opt_str: the option string seen on the command line.
@type opt_str: str
@param value: the argument for the option.
@type value: str
@param parser: the MDANSE option parser.
@type parser: instance of MDANSEOptionParser
'''
trajName = parser.rargs[0]
inputTraj = REGISTRY["input_data"]["mmtk_trajectory"](trajName)
print inputTraj.info()
def error(self, msg):
'''Called when an error occured in the command line.
@param msg: the error message.
@type msg: str
'''
self.print_help(sys.stderr)
print "\n"
self.exit(2, "Error: %s\n" % msg)
def query_classes_registry(self, option, opt_str, value, parser):
'''
Callback that displays the list of the jobs available in MDANSE
@param option: the Option instance calling the callback.
@param opt_str: the option string seen on the command-line triggering the callback
@param value: the argument to this option seen on the command-line.
@param parser: the MDANSEOptionParser instance.
'''
if len(parser.rargs) == 0:
print "Registered interfaces:"
for interfaceName in REGISTRY.get_interfaces():
print "\t- %s" % interfaceName
elif len(parser.rargs) == 1:
val = parser.rargs[0]
print REGISTRY.info(val.lower())
else:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
def run_job(self, option, opt_str, value, parser):
'''Run job file(s).
@param option: the option that triggered the callback.
@type option: optparse.Option instance
@param opt_str: the option string seen on the command line.
@type opt_str: str
@param value: the argument for the option.
@type value: str
@param parser: the MDANSE option parser.
@type parser: instance of MDANSEOptionParser
'''
if len(parser.rargs) != 1:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
filename = parser.rargs[0]
if not os.path.exists(filename):
raise CommandLineParserError("The job file %r could not be executed" % filename)
subprocess.Popen([sys.executable, filename])
def save_job_template(self, option, opt_str, value, parser):
'''
Save job templates.
@param option: the option that triggered the callback.
@type option: optparse.Option instance
@param opt_str: the option string seen on the command line.
@type opt_str: str
@param value: the argument for the option.
@type value: str
@param parser: the MDANSE option parser.
@type parser: instance of MDANSEOptionParser
'''
if len(parser.rargs) != 1:
raise CommandLineParserError("Invalid number of arguments for %r option" % opt_str)
jobs = REGISTRY["job"]
name = parser.rargs[0]
# A name for the template is built.
filename = os.path.abspath('template_%s.py' % name.lower())
jobs[name].save(filename)
# Try to save the template for the job.
try:
jobs[name].save(filename)
# Case where an error occured when writing the template.
except IOError:
raise CommandLineParserError("Could not write the job template as %r" % filename)
# If the job class has no save method, thisis not a valid MDANSE job.
except KeyError:
raise CommandLineParserError("The job %r is not a valid MDANSE job" % name)
# Otherwise, print some information about the saved template.
else:
print "Saved template for job %r as %r" % (name, filename)
......@@ -27,7 +27,7 @@
'''
Created on Mar 30, 2015
@author: Eric C. Pellegrini
:author: Eric C. Pellegrini
'''
import abc
......@@ -108,8 +108,6 @@ class ClassRegistry(abc.ABCMeta):
Only the classes that are metaclassed by ClassRegistry will be registered.
:param cls: the ClassRegistry instance
:type: ClassRegistry
:param packageDir: the package for which all modules should be imported
:type packageDir: str
'''
......@@ -135,12 +133,13 @@ class ClassRegistry(abc.ABCMeta):
@classmethod
def info(cls, interface):
'''
Returns informations about the subclasses of a given base class stored in the registry.
Returns informations about the subclasses of a given base class stored in the registry.
:param cls: the ClassRegistry instance
:type cls: ClassRegistry
:param interface: the name of base class of whom information about its subclasses is requested
:type interface: str
:return: return the stringified list of subclasses of a given registered interface.
:rtype: str
'''
if not cls._registry.has_key(interface):
......@@ -193,8 +192,8 @@ class ClassRegistry(abc.ABCMeta):
'''
Returns the interfaces that are currently registered.
:param cls: the ClassRegsitry instance
:type cls: ClassRegistry
:return: the interfaces currently registered.
:rtype: list of str
'''
return sorted(cls._registry.keys())
\ No newline at end of file
......@@ -27,7 +27,7 @@
'''
Created on Mar 30, 2015
@author: Eric C. Pellegrini
:author: Eric C. Pellegrini
'''
import abc
......@@ -51,7 +51,7 @@ class PreferencesItem(object):
'''
This is the base class for defining a preferences item.
A preferences item implements is a light object used to check preferences before setting them
A preferences item implements is a light object used to check preferences before setting them
but also classify preferences according to their section for a further use in MDANSE GUI.
'''
......@@ -229,7 +229,7 @@ class Preferences(object):
'''
This class implements the MDANSE preferences.
:note: Preferences are defined using the ConfigParser python module that allows to read and write
:note: Preferences are defined using the ConfigParser python module that allows to read and write \
preferences stored in a formatted INI file (RFC822).
'''
......
......@@ -89,7 +89,6 @@ class MasterProcessError(Exception):
pass
class MasterProcess(object):
"""
Master process in a master-slave setup
......@@ -163,9 +162,9 @@ class MasterProcess(object):
pass
def requestTask(self, tag, *parameters):
"""
'''
Launches a task request. The task will be executed by a slave
process in a method called "do_"+tag that is called with the
process in a method called 'do\_'+tag that is called with the
parameters given in the task request. Note that the order of
task executions is not defined.
......@@ -179,7 +178,8 @@ class MasterProcess(object):
:return: a unique task id
:rtype: C{str}
"""
'''
return self.task_manager.addTaskRequest(tag, parameters)
def retrieveResult(self, tag=None):
......@@ -285,15 +285,14 @@ exec slave_code % port in namespace
process.stdin.close()
class SlaveProcess(object):
"""
Slave process in a master-slave setup
A concrete slave process in a program is implemented by subclassing
this class and adding the methods that handle the computational
tasks. Such a method has the name "do_" followed by the tag of the
tasks. Such a method has the name 'do\_' followed by the tag of the
computational task. The process is then launched by calling the
method "start".
method 'start'.
"""
def __init__(self, label, master_host=None, watchdog_period=120.):
......@@ -542,7 +541,7 @@ def initializeMasterProcess(label, slave_script=None, slave_module=None,
:rtype: L{MasterProcess}
"""
import atexit
import os
process = MasterProcess(label, use_name_server)
atexit.register(process.shutdown)
if slave_script is not None or slave_module is not None:
......
......@@ -22,7 +22,7 @@
#
#You should have received a copy of the GNU Lesser General Public
#License along with this library; if not, write to the Free Software
#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
'''
Created on Mar 30, 2015
......@@ -56,8 +56,9 @@ def do_run_step(job, step):
return job.run_step(step)
from MDANSE.DistributedComputing.MasterSlave import startSlaveProcess
# Start the slave process
startSlaveProcess(master_host="localhost:%d")
if __name__ == "__builtin__":
from MDANSE.DistributedComputing.MasterSlave import startSlaveProcess
# Start the slave process
startSlaveProcess(master_host="localhost:%d")
......@@ -309,8 +309,9 @@ sys.modules[__name__ + ".moves.urllib.response"] = Module_six_moves_urllib_respo
class Module_six_moves_urllib_robotparser(types.ModuleType):
"""Lazy loading of moved objects in six.moves.urllib_robotparser"""
'''Lazy loading of moved objects in six.moves.urllib_robotparser.
'''
_urllib_robotparser_moved_attributes = [
MovedAttribute("RobotFileParser", "robotparser", "urllib.robotparser"),
......
......@@ -27,7 +27,7 @@
'''
Created on Mar 30, 2015
@author: pellegrini
:author: Eric C. Pellegrini
'''
import collections
......@@ -48,8 +48,8 @@ class Configurable(object):
Within that framework, to be configurable, a class must:
#. derive from this class
#. implement the "configurators" class attribute as a list of 3-tuple whose: