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

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')])
]
CMDCLASS = {'build' : mdanse_build,
'build_ext' : cython_build_ext}
CMDCLASS = {'build_ext' : cython_build_ext}
if sphinx:
CMDCLASS['build_api'] = mdanse_build_api
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment