Merge branch 'feature-sphinx_doc' into 'develop'

Feature sphinx doc

See merge request !26

BuildServer/Windows/build.bat

@@ -32,19 +32,14 @@ rmdir /S /Q scientific-python
 git clone https://code.ill.fr/scientific-software/scientific-python.git
 cd scientific-python
 git checkout master
-%PYTHON_EXE% setup.py build --netcdf_prefix="%MDANSE_DEPENDENCIES_DIR%\\NetCDF" --netcdf_dll="%MDANSE_DEPENDENCIES_DIR%\\NetCDF"
+%PYTHON_EXE% setup.py build --netcdf_prefix="%MDANSE_DEPENDENCIES_DIR%\\NetCDF" --netcdf_dll="%MDANSE_DEPENDENCIES_DIR%\\NetCDF" install
 set STATUS=%ERRORLEVEL%
 rem Exit now if unable to build
 if %STATUS% neq 0 (
     echo "Failed to build Scientific"
     exit %STATUS%
 )
-%PYTHON_EXE% setup.py install
-rem Exit now if unable to install
-if %STATUS% neq 0 (
-    echo "Failed to install Scientific"
-    exit %STATUS%
-)
+
 rem Copy netcdf dependencies
 copy "%MDANSE_DEPENDENCIES_DIR%\\NetCDF\\netcdf.dll" "%MDANSE_TEMPORARY_INSTALLATION_DIR%\\Lib\\site-packages\\Scientific\\"
 copy "%MDANSE_DEPENDENCIES_DIR%\\NetCDF\\netcdf.h" "%MDANSE_TEMPORARY_INSTALLATION_DIR%\\include\\Scientific\\"
@@ -57,37 +52,25 @@ rmdir /S /Q mmtk
 git clone https://code.ill.fr/scientific-software/mmtk.git
 cd mmtk
 git checkout master
-%PYTHON_EXE% setup.py build
+%PYTHON_EXE% setup.py build install
 set STATUS=%ERRORLEVEL%
 rem Exit now if unable to build
 if %STATUS% neq 0 (
     echo "Failed to build MMTK"
     exit %STATUS%
 )
-%PYTHON_EXE% setup.py install
-rem Exit now if unable to install
-if %STATUS% neq 0 (
-    echo "Failed to install MMTK"
-    exit %STATUS%
-)
+
 cd ..
 rmdir /S /Q mmtk
 
 rem Go back to the MDANSE source directory and build and install it
 cd "%MDANSE_SOURCE_DIR%"
-%PYTHON_EXE% setup.py build
+%PYTHON_EXE% setup.py build install
 set STATUS=%ERRORLEVEL%
 rem Exit now if unable to build
 if %STATUS% neq 0 (
     echo "Failed to build MDANSE"
     exit %STATUS%
 )
-%PYTHON_EXE% setup.py install
-rem Exit now if unable to install
-if %STATUS% neq 0 (
-    echo "Failed to install MDANSE"
-    exit %STATUS%
-)
-rmdir /S /Q build
 
-cd %MDANSE_SOURCE_DIR%
+cd %MDANSE_SOURCE_DIR%
\ No newline at end of file

BuildServer/Windows/clean.bat

-@echo off
-rem VERSION_NAME
-rem MDANSE_SOURCE_DIR
-rem BUILD_TARGET
-rem MDANSE_DEPENDENCIES_DIR
-rem MDANSE_TEMPORARY_INSTALLATION_DIR
-
-cd %MDANSE_SOURCE_DIR%
-del MDANSE*.exe
-rmdir /S /Q build
-rmdir /S /Q BuildServer\\Windows\\Build
-
-rmdir /S /Q %MDANSE_TEMPORARY_INSTALLATION_DIR%
-
-rem Mandatory to ensure the script will exit withour error
-cd %MDANSE_SOURCE_DIR%
\ No newline at end of file

BuildServer/Windows/deploy.bat

@@ -5,23 +5,43 @@ rem BUILD_TARGET
 rem MDANSE_DEPENDENCIES_DIR
 rem MDANSE_TEMPORARY_INSTALLATION_DIR
 
+cd %MDANSE_SOURCE_DIR%
+
+rem Set the path to python executable
+set PYTHON_EXE=%MDANSE_TEMPORARY_INSTALLATION_DIR%\\python.exe
+
+rem This is the env var used by distutils to find the MSVC framework to be used for compiling extension
+rem see https://stackoverflow.com/questions/2817869/error-unable-to-find-vcvarsall-bat for more info
+rem For the sake of code safety, this should be the same framework used to build Python itself
+rem see http://p-nand-q.com/python/building-python-27-with-vs2010.html for more info
+set VS90COMNTOOLS=C:\Users\\ci\\AppData\\Local\\Programs\\Common\\Microsoft\\Visual C++ for Python\\9.0\\Common7\\Tools
+
+%PYTHON_EXE% setup.py build_api build_help install
+
+set STATUS=%ERRORLEVEL%
+rem Exit now if unable to build
+if %STATUS% neq 0 (
+    echo "Failed to build MDANSE Documentation"
+    exit %STATUS%
+)
+
 cd "%MDANSE_SOURCE_DIR%\\BuildServer\\Windows"
 
 rem copy LICENSE
-copy %MDANSE_SOURCE_DIR%\\LICENSE %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Windows_resources\\nsis\\
+copy %MDANSE_SOURCE_DIR%\\LICENSE %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Resources\\nsis\\
 
 rem copy CHANGELOG to CHANGELOG.txt (compulsory to be opened by nsis through an external text editor)
-copy %MDANSE_SOURCE_DIR%\\CHANGELOG %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Windows_resources\\nsis\\CHANGELOG.txt
+copy %MDANSE_SOURCE_DIR%\\CHANGELOG %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Resources\\nsis\\CHANGELOG.txt
 
 rem Copy site.py 
-copy %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Windows_resources\\site.py %MDANSE_TEMPORARY_INSTALLATION_DIR%\\Lib\\
+copy %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Resources\\site.py %MDANSE_TEMPORARY_INSTALLATION_DIR%\\Lib\\
 
 rem Copy Visual dll see https://stackoverflow.com/questions/214852/python-module-dlls to understand why dll copy destination folder must be the Scientific folder
 copy "%MDANSE_DEPENDENCIES_DIR%\\NetCDF\\vcruntime140.dll" "%MDANSE_TEMPORARY_INSTALLATION_DIR%\\Lib\\site-packages\\Scientific\\"
 
 rem create the MDANSE installer
 echo "Creating nsis installer for target %MDANSE_TEMPORARY_INSTALLATION_DIR%..."
-makensis /V4 /ONSISlog.txt /DVERSION=%VERSION_NAME% /DARCH=%BUILD_TARGET% /DTARGET_DIR=%MDANSE_TEMPORARY_INSTALLATION_DIR% %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Windows_resources\\nsis\\MDANSE_installer.nsi
+makensis /V4 /ONSISlog.txt /DVERSION=%VERSION_NAME% /DARCH=%BUILD_TARGET% /DTARGET_DIR=%MDANSE_TEMPORARY_INSTALLATION_DIR% %MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Resources\\nsis\\MDANSE_installer.nsi
 
 set STATUS=%ERRORLEVEL%
 rem Exit now if something goes wrong
@@ -33,4 +53,5 @@ if %STATUS% neq 0 (
 move %MDANSE_TEMPORARY_INSTALLATION_DIR%\\MDANSE*.exe %MDANSE_SOURCE_DIR%\\
 rem Remove NSIS log file
 del NSISlog.txt
+
 cd %MDANSE_SOURCE_DIR%

BuildServer/Windows/tests.bat

@@ -13,7 +13,10 @@ if "%1%"=="win32" (
 	set BUILD_TARGET=win-amd64
 )
 
+set PYTHONPATH=%MDANSE_SOURCE_DIR%/build/lib;%PYTHONPATH%
+
 set MDANSE_SOURCE_DIR=%cd%
+
 rem Set the site-packages of the temporary Python
 set PYTHON_SCRIPT_DIR=%MDANSE_SOURCE_DIR%\\BuildServer\\Windows\\Build\\Scripts
 rem Set the location where the temporary Python will be installed
@@ -61,4 +64,4 @@ if %STATUS% neq 0 (
     exit %STATUS%
 )
 
-cd %MDANSE_SOURCE_DIR%
+cd %MDANSE_SOURCE_DIR%
\ No newline at end of file

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)
-	

Extensions/xtc/src/xdrfile.c

@@ -782,10 +782,10 @@ xdrfile_decompress_coord_float(float     *ptr,
 							   XDRFILE*   xfp)
 {
 	int minint[3], maxint[3], *lip;
-	int smallidx, minidx, maxidx;
+	int smallidx;
 	unsigned sizeint[3], sizesmall[3], bitsizeint[3], size3;
 	int k, *buf1, *buf2, lsize, flag;
-	int smallnum, smaller, larger, i, is_smaller, run;
+	int smallnum, smaller, i, is_smaller, run;
 	float *lfp, inv_precision;
 	int tmp, *thiscoord,  prevcoord[3];
 	unsigned int bitsize;
@@ -866,14 +866,11 @@ xdrfile_decompress_coord_float(float     *ptr,
 		return 0; /* not sure what has happened here or why we return... */
 	}
 	tmp=smallidx+8;
-	maxidx = (LASTIDX<tmp) ? LASTIDX : tmp;
-	minidx = maxidx - 8; /* often this equal smallidx */
 	tmp = smallidx-1;
 	tmp = (FIRSTIDX>tmp) ? FIRSTIDX : tmp;
 	smaller = magicints[tmp] / 2;
 	smallnum = magicints[smallidx] / 2;
 	sizesmall[0] = sizesmall[1] = sizesmall[2] = magicints[smallidx] ;
-	larger = magicints[maxidx];
 
 	/* buf2[0] holds the length in bytes */
   
@@ -1013,7 +1010,6 @@ xdrfile_compress_coord_float(float   *ptr,
 	float *lfp, lf;
 	int tmp, tmpsum, *thiscoord,  prevcoord[3];
 	unsigned int tmpcoord[30];
-	int errval=1;
 	unsigned int bitsize;
   
 	if(xfp==NULL)
@@ -1074,7 +1070,6 @@ xdrfile_compress_coord_float(float   *ptr,
         {
 			/* scaling would cause overflow */
 			fprintf(stderr, "(xdrfile error) Internal overflow compressing coordinates.\n");
-			errval=0;
 		}
 		lint1 = lf;
 		if (lint1 < minint[0]) minint[0] = lint1;
@@ -1089,7 +1084,6 @@ xdrfile_compress_coord_float(float   *ptr,
         {
 			/* scaling would cause overflow */
 			fprintf(stderr, "(xdrfile error) Internal overflow compressing coordinates.\n");
-			errval=0;
 		}
 		lint2 = lf;
 		if (lint2 < minint[1]) minint[1] = lint2;