Sphinx is now a command apart from build

Removed some sphinx warnings

.gitlab-ci.yml

@@ -137,6 +137,7 @@ ci:osx:
     - source ${CI_PROJECT_DIR}/BuildServer/Unix/version.sh
     - ${CI_PROJECT_DIR}/BuildServer/Unix/build.sh
     - ${CI_PROJECT_DIR}/BuildServer/Unix/tests.sh
+    - ${CI_PROJECT_DIR}/BuildServer/Unix/deploy_macos.sh
   allow_failure: false
   artifacts:
     paths:

BuildServer/Unix/build.sh

@@ -62,6 +62,9 @@ cd $MDANSE_SOURCE_DIR
 
 # Now build last version and install it
 ${PYTHONEXE} setup.py build
+${PYTHONEXE} setup.py build_api
+${PYTHONEXE} setup.py build_help
+
 status=$?
 if [ $status -ne 0 ]; then
 	echo -e "${RED}" "Failed to build MDANSE""${NORMAL}"
@@ -74,4 +77,4 @@ if [ $status -ne 0 ]; then
 	exit $status
 fi
 
-rm -rf build
\ No newline at end of file
+rm -rf build

Doc/Template.py

-"""This module illustrates how to write your docstring in OpenAlea
-and other projects related to OpenAlea."""
-
-__license__ = "Cecill-C"
-__revision__ = " $Id: actor.py 1586 2009-01-30 15:56:25Z cokelaer $ "
-__docformat__ = 'reStructuredText'
-
-
-class MainClass1(object):
-    """This class docstring shows how to use sphinx and rst syntax
-
-    The first line is brief explanation, which may be completed with 
-    a longer one. For instance to discuss about its methods. The only
-    method here is :func:`function1`'s. The main idea is to document
-    the class and methods's arguments with 
-
-    - **parameters**, **types**, **return** and **return types**::
-
-          :param arg1: description
-          :param arg2: description
-          :type arg1: type description
-          :type arg1: type description
-          :return: return description
-          :rtype: the return type description
-
-    - and to provide sections such as **Example** using the double commas syntax::
-
-          :Example:
-
-          followed by a blank line !
-
-      which appears as follow:
-
-      :Example:
-
-      followed by a blank line
-
-    - Finally special sections such as **See Also**, **Warnings**, **Notes**
-      use the sphinx syntax (*paragraph directives*)::
-
-          .. seealso:: blabla
-          .. warnings also:: blabla
-          .. note:: blabla
-          .. todo:: blabla
-
-    .. note::
-        There are many other Info fields but they may be redundant:
-            * param, parameter, arg, argument, key, keyword: Description of a
-              parameter.
-            * type: Type of a parameter.
-            * raises, raise, except, exception: That (and when) a specific
-              exception is raised.
-            * var, ivar, cvar: Description of a variable.
-            * returns, return: Description of the return value.
-            * rtype: Return type.
-
-    .. note::
-        There are many other directives such as versionadded, versionchanged,
-        rubric, centered, ... See the sphinx documentation for more details.
-
-    Here below is the results of the :func:`function1` docstring.
-
-    """
-
-    def function1(self, arg1, arg2, arg3):
-        """returns (arg1 / arg2) + arg3
-
-        This is a longer explanation, which may include math with latex syntax
-        :math:`\\alpha`.
-        Then, you need to provide optional subsection in this order (just to be
-        consistent and have a uniform documentation. Nothing prevent you to
-        switch the order):
-
-          - parameters using ``:param <name>: <description>``
-          - type of the parameters ``:type <name>: <description>``
-          - returns using ``:returns: <description>``
-          - examples (doctest)
-          - seealso using ``.. seealso:: text``
-          - notes using ``.. note:: text``
-          - warning using ``.. warning:: text``
-          - todo ``.. todo:: text``
-
-        **Advantages**:
-         - Uses sphinx markups, which will certainly be improved in future
-           version
-         - Nice HTML output with the See Also, Note, Warnings directives
-
-
-        **Drawbacks**:
-         - Just looking at the docstring, the parameter, type and  return
-           sections do not appear nicely
-
-        :param arg1: the first value
-        :param arg2: the first value
-        :param arg3: the first value
-        :type arg1: int, float,...
-        :type arg2: int, float,...
-        :type arg3: int, float,...
-        :returns: arg1/arg2 +arg3
-        :rtype: int, float
-
-        :Example:
-
-        >>> import Template
-        >>> a = Template.MainClass1()
-        >>> a.function1(1,1,1)
-        2
-
-        .. note:: can be useful to emphasize
-            important feature
-        .. seealso:: :class:`MainClass2`
-        .. warning:: arg2 must be non-zero.
-        .. todo:: check that arg2 is non zero.
-        """
-        return arg1/arg2 + arg3
-
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod()
\ No newline at end of file

Doc/Template.rst

-.. automodule:: Template
-    :members:
-    :undoc-members:
-    :inherited-members:
-    :show-inheritance:
\ No newline at end of file

Doc/build_doc.sh

-#!/bin/sh
-
-MDANSE_API="../MDANSE/Doc/API"
-
-#rm -rf ${MDANSE_API}
-
-#mkdir -p ${MDANSE_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 ../MDANSE/Externals
-
-cp conf_html.py ${MDANSE_API}/conf.py
-
-cp layout.html ${MDANSE_API}/_templates/
-
-cp mdanse_logo.png ${MDANSE_API}/_static/
-
-sphinx-build -b html ${MDANSE_API} ${MDANSE_API}
-
-

Doc/build_help.sh

-#!/bin/sh
-
-MDANSE_HELP="../MDANSE/Doc/Help"
-
-rm -rf ${MDANSE_HELP}
-
-mkdir -p ${MDANSE_HELP}
-mkdir ${MDANSE_HELP}/_static
-mkdir ${MDANSE_HELP}/_templates
-
-sphinx-apidoc -o  ${MDANSE_HELP} -F --separate -d 5 -H MDANSE -A "G. Goret & E. Pellegrini"  -V 1.0 -R 1.0 ../MDANSE
-
-cp conf_help.py ${MDANSE_HELP}/conf.py
-
-cp layout.html ${MDANSE_HELP}/_templates/
-
-cp mdanse_logo.png ${MDANSE_HELP}/_static/
-
-sphinx-build -b htmlhelp ${MDANSE_HELP} ${MDANSE_HELP}

Doc/build_theory.sh

-#!/bin/sh
-
-latex theory_help.tex
-makeglossaries theory_help
-latex theory_help.tex
-latex theory_help.tex
-dvipdf theory_help.dvi
-
-mv theory_help.pdf ../MDANSE/Doc
-
-rm theory_help.acn
-rm theory_help.acr
-rm theory_help.alg
-rm theory_help.aux
-rm theory_help.dvi
-rm theory_help.glo
-rm theory_help.ist
-rm theory_help.out
-rm theory_help.log
-rm theory_help.toc
-

Doc/conf_html.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 sys, os
-#
-# 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(os.path.abspath('../MDANSE'))
-
-# -- 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, G. Goret & B. Aoun & E. 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'
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_patterns = ['MDANSE.Externals','_build', '**Tests**']
-
-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'B. Aoun \\& G. Goret \\& E. Pellegrini', 'manual'),
-]
-
-pdf_documents = [('index', 'MDANSE', u'MDANSE Documentation', u'G. Goret & B. Aoun & E. 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'G. Goret & B. Aoun & E. 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'G. Goret & B. Aoun & E. Pellegrini','MDANSE', 'One line description of project.','Miscellaneous'),]
-
-exclude_patterns = ['MDANSE.Externals**', 'MDANSE.__pkginfo__']
-
-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/Framework/Configurators/AtomSelectionConfigurator.py

@@ -33,7 +33,6 @@ Created on Mar 30, 2015
 import collections
 import operator
 
-
 from MDANSE import ELEMENTS, REGISTRY
 from MDANSE.Framework.UserDefinitionStore import UD_STORE
 from MDANSE.Framework.Configurators.IConfigurator import IConfigurator, ConfiguratorError
@@ -47,7 +46,7 @@ LEVELS["residue"]  = {"atom" : 0, "atomcluster" : 1, "molecule" : 1, "nucleotide
 LEVELS["chain"]    = {"atom" : 0, "atomcluster" : 1, "molecule" : 1, "nucleotidechain" : 3, "peptidechain" : 3, "protein" : 3}
 LEVELS["molecule"] = {"atom" : 0, "atomcluster" : 1, "molecule" : 1, "nucleotidechain" : 3, "peptidechain" : 3, "protein" : 4}
 
-class AtomSelectionConfigurator(IConfigurator):    
+class AtomSelectionConfigurator(IConfigurator):
     '''
     This configurator allows the selection of a specific set of atoms on which the analysis will be performed.
 
@@ -55,82 +54,77 @@ class AtomSelectionConfigurator(IConfigurator):
     
     After the call to :py:meth:`~MDANSE.Framework.Configurators.AtomSelectionConfigurator.AtomSelectionConfigurator.configure` method 
     the following keys will be available for this configurator
-    
+
     #. value: the input value used to configure this configurator
-    #. indexes: the sorted (in increasing order) MMTK indexes of the selected atoms 
+    #. indexes: the sorted (in increasing order) MMTK indexes of the selected atoms
     #. n_selected_atoms: the number of selected atoms
-    #. elements: a nested-list of the chemical symbols of the selected atoms. The size of the nested list depends on the 
-    grouping_level selected via :py:class:`~MDANSE.Framework.Configurators.GroupingLevelConfigurator.GroupingLevelConfigurator`
-    configurator.
+    #. elements: a nested-list of the chemical symbols of the selected atoms. The size of the nested list depends on the grouping_level selected via :py:class:`~MDANSE.Framework.Configurators.GroupingLevelConfigurator.GroupingLevelConfigurator` configurator.
     
-        
-    :note: this configurator depends on :py:class:`~MDANSE.Framework.Configurators.MMTKTrajectoryConfigurator.MMTKTrajectoryConfigurator` 
-    and :py:class:`~MDANSE.Framework.Configurators.GroupingLevelConfigurator.GroupingLevelConfigurator` configurators to be configured
+    :note: this configurator depends on :py:class:`~MDANSE.Framework.Configurators.MMTKTrajectoryConfigurator.MMTKTrajectoryConfigurator` and :py:class:`~MDANSE.Framework.Configurators.GroupingLevelConfigurator.GroupingLevelConfigurator` configurators to be configured
     '''
-    
+
     _default = "all"
-                    
+
     def configure(self, value):
         '''
         Configure an input value. 
         
-        The value must be a string that can be either an atom selection string or a valid user 
-        definition.
+        The value must be a string that can be either an atom selection string or a valid user definition.
         
         :param value: the input value
         :type value: str
         '''
-                          
+
         trajConfig = self._configurable[self._dependencies['trajectory']]
-        
+
         if value is None:
             value = ['all']
-        
+
         if isinstance(value,basestring):
             value = [value]
 
         if not isinstance(value,(list,tuple)):
             raise ConfiguratorError("Invalid input value.")
-        
+
         self["value"] = value
-        
+
         indexes = set()
 
         for v in value:
-        
+
             if UD_STORE.has_definition(trajConfig["basename"],"atom_selection",v):
                 ud = UD_STORE.get_definition(trajConfig["basename"],"atom_selection",v)
                 indexes.update(ud["indexes"])
-            else:        
+            else:
                 parser = AtomSelectionParser(trajConfig["instance"])
                 indexes.update(parser.parse(v))
 
         self["flatten_indexes"] = sorted(list(indexes))
-        
+
         trajConfig = self._configurable[self._dependencies['trajectory']]
 
         atoms = sorted(trajConfig["universe"].atomList(), key = operator.attrgetter('index'))
         selectedAtoms = [atoms[idx] for idx in indexes]
 
-        self["selection_length"] = len(self["flatten_indexes"])        
+        self["selection_length"] = len(self["flatten_indexes"])
         self['indexes'] = [[idx] for idx in self["flatten_indexes"]]
 
         self['elements'] = [[at.symbol] for at in selectedAtoms]
         self['names'] = [at.symbol for at in selectedAtoms]
         self['unique_names'] = sorted(set(self['names']))
         self['masses'] = [[ELEMENTS[n,'atomic_weight']] for n in self['names']]
-                
+
     def get_natoms(self):
-                
+
         nAtomsPerElement = {}
         for v in self["names"]:
             if nAtomsPerElement.has_key(v):
                 nAtomsPerElement[v] += 1
             else:
                 nAtomsPerElement[v] = 1
-                
+
         return nAtomsPerElement
-    
+
     def get_indexes(self):
 
         indexesPerElement = {}
@@ -139,9 +133,9 @@ class AtomSelectionConfigurator(IConfigurator):
                 indexesPerElement[v].extend(self['indexes'][i])
             else:
                 indexesPerElement[v] = self['indexes'][i][:]
-                
+
         return indexesPerElement
-            
+
     def get_information(self):
         '''
         Returns some informations the atom selection.
@@ -152,11 +146,11 @@ class AtomSelectionConfigurator(IConfigurator):
 
         if not self.has_key("selection_length"):
             return "Not configured yet\n"
-        
+
         info = []
         info.append("Number of selected atoms:%d" % self["selection_length"])
         info.append("Selected elements:%s" % self["unique_names"])
-        
+
         return "\n".join(info)
-    
+
 REGISTRY["atom_selection"] = AtomSelectionConfigurator

setup.py

 import fnmatch
 import glob
 import os
+import subprocess
 import sys
 
 import numpy
@@ -168,52 +169,46 @@ SCRIPTS = glob.glob(os.path.join(SCRIPTS_PATH,'mdanse*'))
 #################################
 
 if sphinx:
-    import sphinx.apidoc
-    import sphinx.setup_command
 
+    import sphinx.setup_command
     class mdanse_build_doc(sphinx.setup_command.BuildDoc):
-                              
+
         def run(self):
             
             build = self.get_finalized_command('build')
                     
             buildDir = os.path.abspath(build.build_lib)
 
+            if not os.path.exists(buildDir):
+                raise IOError("build command must be performed prior building the doc")
+
             sys.path.insert(0,buildDir)
 
-            sphinxDir = os.path.join(build.build_base,'sphinx',self.doctype)
+            sphinxDir = os.path.abspath(os.path.join(build.build_base,'sphinx',self.doctype))
+
+            if not os.path.exists(sphinxDir):
+                os.mkdir(sphinxDir)
                                  
             metadata = self.distribution.metadata
+
+            args = ["sphinx-apidoc",
+                    "-F",
+                    "--separate",
+                    "-H%s" % metadata.name,
+                    "-A%s" % metadata.author,
+                    "-R%s" % metadata.version,
+                    "-o%s" % sphinxDir,
+                    os.path.join(buildDir,'MDANSE'),
+                    os.path.join(buildDir,'MDANSE','Externals')]
+
+            p = subprocess.call(args)
+                             
+            currentDirectory = os.getcwd()
             
-            # /!\ apidoc.main is deprecated. The API has been broken in sphinx 1.7.0, see https://github.com/sphinx-doc/sphinx/issues/4615
-            if int(sphinx.__version__.split(".")[1]) <= 6:
-                sphinx.apidoc.main(['',
-                                '-F',
-                                '--separate',
-                                '-H', metadata.name,
-                                '-A', metadata.author,
-                                '-V', metadata.version,
-                                '-R', metadata.version,
-                                '-o', sphinxDir,
-                                os.path.join(buildDir,'MDANSE'),
-                                os.path.join(buildDir,'MDANSE','Externals')])
-            else:
-                sphinx.apidoc.main('', [
-                                '-F',
-                                '--separate',
-                                '-H', metadata.name,
-                                '-A', metadata.author,
-                                '-V', metadata.version,
-                                '-R', metadata.version,
-                                '-o', sphinxDir,
-                                os.path.join(buildDir,'MDANSE'),
-                                os.path.join(buildDir,'MDANSE','Externals')])
-            curDir = os.getcwd()
-                 
             import shutil
-            shutil.copy(os.path.join(curDir,'Doc','conf_%s.py' % self.doctype),os.path.join(sphinxDir,'conf.py'))
-            shutil.copy(os.path.join(curDir,'Doc','mdanse_logo.png'),os.path.join(sphinxDir,'_static'))
-            shutil.copy(os.path.join(curDir,'Doc','layout.html'),os.path.join(sphinxDir,'_templates'))
+            shutil.copy(os.path.join(currentDirectory,'Doc','conf_%s.py' % self.doctype),os.path.join(sphinxDir,'conf.py'))
+            shutil.copy(os.path.join(currentDirectory,'Doc','mdanse_logo.png'),os.path.join(sphinxDir,'_static'))
+            shutil.copy(os.path.join(currentDirectory,'Doc','layout.html'),os.path.join(sphinxDir,'_templates'))
      
             # The directory where the rst files are located.
             self.source_dir = sphinxDir
@@ -223,8 +218,8 @@ if sphinx:
             # The directory where the documentation will be built
             self.build_dir = os.path.join(buildDir,'MDANSE','Doc',self.doctype)
             
-            self.finalize_options()
-                                                     
+            self.builder_target_dir = os.path.join(self.build_dir, self.builder)
+                                                                 
             sphinx.setup_command.BuildDoc.run(self)
                  
             sys.path.pop(0)
@@ -241,15 +236,15 @@ if sphinx:
 # Debian packaging
 #################################
 
-class mdanse_build(build):
+#class mdanse_build(build):
 
-    def has_sphinx(self):
-        if sphinx is None:
-            return False
-        setup_dir = os.path.dirname(os.path.abspath(__file__))
-        return os.path.isdir(os.path.join(setup_dir, 'Doc'))
+#    def has_sphinx(self):
+#        if sphinx is None:
+#            return False
+#        setup_dir = os.path.dirname(os.path.abspath(__file__))
+#        return os.path.isdir(os.path.join(setup_dir, 'Doc'))
     
-    sub_commands = build.sub_commands + [('build_api', has_sphinx),('build_help',has_sphinx)]
+#    sub_commands = build.sub_commands# + [('build_api', has_sphinx),('build_help',has_sphinx)]
                         
 #################################
 # Extensions section
@@ -287,8 +282,7 @@ EXTENSIONS = [Extension('MDANSE.Extensions.distance_histogram',
                         sources=glob.glob(os.path.join('Extensions','xtc','src','*.c')) + [os.path.join('Extensions','xtc','xtc.pyx')])
               ]
 
-CMDCLASS = {'build'     : mdanse_build,
-            'build_ext' : cython_build_ext}
+CMDCLASS = {'build_ext' : cython_build_ext}
 
 if sphinx:
     CMDCLASS['build_api'] = mdanse_build_api