Commit c117286e authored by eric pellegrini's avatar eric pellegrini
Browse files

Merge branch 'feature-sphinx_doc' into 'develop'

Feature sphinx doc

See merge request !26
parents 017616ad fdb9294c
Pipeline #4229 passed with stages
in 36 minutes and 53 seconds
......@@ -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%
\ No newline at end of file
cd %MDANSE_SOURCE_DIR%
@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
......@@ -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%
......@@ -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%
\ No newline at end of file
cd %MDANSE_SOURCE_DIR%
"""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
.. automodule:: Template
:members:
:undoc-members:
:inherited-members:
:show-inheritance:
\ No newline at end of file
#!/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}
#!/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}
#!/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
#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)
This diff is collapsed.
......@@ -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;
......@@ -1100,10 +1094,6 @@ xdrfile_compress_coord_float(float *ptr,
lf = *lfp * precision + 0.5;
else
lf = *lfp * precision - 0.5;
if (fabs(lf) > INT_MAX-2)
{
errval=0;
}
lint3 = lf;
if (lint3 < minint[2]) minint[2] = lint3;
if (lint3 > maxint[2]) maxint[2] = lint3;
......@@ -1126,7 +1116,6 @@ xdrfile_compress_coord_float(float *ptr,
* would cause overflow
*/
fprintf(stderr, "(xdrfile error) Internal overflow compressing coordinates.\n");
errval=0;
}
sizeint[0] = maxint[0] - minint[0]+1;
sizeint[1] = maxint[1] - minint[1]+1;
......@@ -1299,10 +1288,10 @@ xdrfile_decompress_coord_double(double *ptr,
XDRFILE* xfp)
{
int minint[3], maxint[3], *lip;
int smallidx, minidx, maxidx;
int smallidx, maxidx;
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;
double *lfp, inv_precision;
float float_prec, tmpdata[30];
int tmp, *thiscoord, prevcoord[3];
......@@ -1381,13 +1370,11 @@ xdrfile_decompress_coord_double(double *ptr,
return 0;
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 */
......@@ -1506,7 +1493,6 @@ xdrfile_compress_coord_double(double *ptr,
float float_prec, lf,tmpdata[30];
int tmp, tmpsum, *thiscoord, prevcoord[3];
unsigned int tmpcoord[30];
int errval=1;
unsigned int bitsize;
bitsizeint[0] = 0;
......@@ -1563,7 +1549,6 @@ xdrfile_compress_coord_double(double *ptr,
if (fabs(lf) > INT_MAX-2) {
/* scaling would cause overflow */
fprintf(stderr, "(xdrfile error) Internal overflow compressing coordinates.\n");
errval=0;
}
lint1 = lf;
if (lint1 < minint[0]) minint[0] = lint1;
......@@ -1577,7 +1562,6 @@ xdrfile_compress_coord_double(double *ptr,
if (fabs(lf) > INT_MAX-2) {
/* scaling would cause overflow */
fprintf(stderr, "(xdrfile error) Internal overflow compressing coordinates.\n");
errval=0;
}
lint2 = lf;
if (lint2 < minint[1]) minint[1] = lint2;
......@@ -1588,9 +1572,6 @@ xdrfile_compress_coord_double(double *ptr,
lf = (float)*lfp * float_prec + 0.5;
else
lf = (float)*lfp * float_prec - 0.5;
if (fabs(lf) > INT_MAX-2) {
errval=0;
}
lint3 = lf;
if (lint3 < minint[2]) minint[2] = lint3;
if (lint3 > maxint[2]) maxint[2] = lint3;
......@@ -1613,7 +1594,6 @@ xdrfile_compress_coord_double(double *ptr,