The code.ill.fr has been recreated and upgraded with the latest version this weekend, If you encounter any problem please inform the Helpdesk.

Commit 92cb4738 authored by eric pellegrini's avatar eric pellegrini
Browse files

Sphinx is now a command apart from build

Removed some sphinx warnings
parent 017616ad
......@@ -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:
......
......@@ -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
"""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)
......@@ -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
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')])