Commit 1af35083 authored by eric pellegrini's avatar eric pellegrini

Added support for building sphinx documentation for small help

Added a new icon for displaying MDANSE API
parent cdf974c1
......@@ -30,29 +30,6 @@ Created on Mar 30, 2015
@author: Gael Goret and Eric C. Pellegrini
'''
# import os
# import shutil
# import sys
#
# import MDANSE
# MDANSE_PATH = os.path.abspath('../MDANSE')
# sys.path.append(os.path.dirname(__file__))
#
# 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(MDANSE_PATH)
# DOC_PATH = os.path.join(MDANSE_PATH,'Doc')
# if not os.path.exists(DOC_PATH):
# os.makedirs(DOC_PATH)
#
# shutil.copy('mdanse_logo.png',DOC_PATH)
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
......
......@@ -27,20 +27,9 @@
'''
Created on Mar 30, 2015
@author: goret
@author: Gael Goret and Eric C. Pellegrini
'''
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'
......@@ -55,14 +44,14 @@ templates_path = ['_templates']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
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'
copyright = u'2015, Gael Goret & Eric C. 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
......@@ -73,10 +62,6 @@ 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='""')
......@@ -92,8 +77,8 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "default"
html_theme_options = {'sidebarwidth':250}#, 'nosidebar':True}
html_theme = "classic"
html_theme_options = {'sidebarwidth':250}
html_show_copyright = False
......@@ -102,35 +87,39 @@ 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'),
]
latex_documents = [('index', 'MDANSE.tex', u'MDANSE Documentation',u'Gael Goret & Eric C. Pellegrini', 'manual'),]
pdf_documents = [('index', 'MDANSE', u'MDANSE Documentation', u'B. Aoun & G. Goret & E. Pellegrini'),]
pdf_documents = [('index', 'MDANSE', u'MDANSE Documentation', u'Gael Goret & Eric C. Pellegrini'),]
exclude_patterns = ['MDANSE.Externals**', 'MDANSE.__pkginfo__']
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_patterns = ['Externals']
members_to_watch = ['class']
from MDANSE import REGISTRY
klsNames = [kls.__name__ for kls in REGISTRY["job"].values()]
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 getattr(obj,'__name__',None) in klsNames:
lines.extend(obj.build_doc().splitlines())
if what in members_to_watch:
# modify the docstring so the rendered output is highlights the omission
if lines:
lines.insert(0,' **Description:**\n\n\n')
# lines.insert(0,' .. inheritance-diagram:: %s\n'%name.split('.')[-1])
# lines.insert(0,'**inheritance-diagram:**\n\n')
lines.insert(0,'')
lines.insert(0,':Description:')
lines.insert(0,'')
exclusions = ('__weakref__','__doc__', '__module__', '__dict__',)
def autodoc_skip_member(app, what, name, obj, skip, options):
if what in ['method','attribut','function','exception']:
return True
exclusions = ('__weakref__', # special-members
'__doc__', '__module__', '__dict__', # undoc-members
)
if name in exclusions:
return True
......
......@@ -15,7 +15,7 @@ class JobHelpFrame(wx.Frame):
fully_qualified_name = 'MDANSE.Framework.Jobs' + '.' + job.__class__.__name__
self._doc = PLATFORM.get_path(os.path.join(PLATFORM.documentation_path(), fully_qualified_name + '.html'))
self._doc = PLATFORM.get_path(os.path.join(PLATFORM.help_path(), fully_qualified_name + '.html'))
self.build()
......
......@@ -31,13 +31,14 @@ Created on Apr 14, 2015
'''
import collections
import os
import webbrowser
import wx
import wx.aui as aui
from MDANSE.__pkginfo__ import __version__, __revision__
from MDANSE import LOGGER, REGISTRY
from MDANSE import LOGGER, PLATFORM, REGISTRY
from MDANSE.Framework.Jobs.Converters.Converter import Converter
from MDANSE.App.GUI import DATA_CONTROLLER
......@@ -146,7 +147,7 @@ class MainFrame(wx.Frame):
udButton = self._toolbar.AddSimpleTool(wx.ID_ANY,ICONS["user",32,32], 'Edit the user definitions')
preferencesButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["preferences",32,32], 'Edit the preferences')
registryButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["registry",32,32], 'Inspect MDANSE classes registry')
helpButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["help",32,32], 'Help')
apiButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["api",32,32], 'Open MDANSE API')
websiteButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["web",32,32], 'Open MDANSE website')
aboutButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["about",32,32], 'About MDANSE')
bugButton = self._toolbar.AddSimpleTool(wx.ID_ANY, ICONS["bug",32,32], 'Bug report')
......@@ -165,7 +166,7 @@ class MainFrame(wx.Frame):
self.Bind(wx.EVT_MENU, self.on_open_classes_registry, registryButton)
self.Bind(wx.EVT_MENU, self.on_about, aboutButton)
self.Bind(wx.EVT_MENU, self.on_quit, quitButton)
self.Bind(wx.EVT_MENU, self.on_help, helpButton)
self.Bind(wx.EVT_MENU, self.on_open_api, apiButton)
self.Bind(wx.EVT_MENU, self.on_open_mdanse_url, websiteButton)
self.Bind(wx.EVT_MENU, self.on_bug_report, bugButton)
......@@ -227,9 +228,14 @@ or directly to the MDANSE mailing list:
f.Show()
def on_help(self, event):
def on_open_api(self, event):
mainHTML = os.path.join(PLATFORM.api_path(),'MDANSE.html')
webbrowser.open('https://github.com/eurydyce/MDANSE/tree/master/MDANSE')
if os.path.exists(mainHTML):
webbrowser.open(mainHTML)
else:
LOGGER("Can not open MDANSE API. Maybe the documentation was not properly installed.", "error",['dialog'])
def on_load_data(self, event=None):
......
......@@ -89,15 +89,25 @@ class Platform(object):
'''
pass
def documentation_path(self):
def api_path(self):
'''
Returns the path for MDANSE HTML documentation.
Returns the path for MDANSE HTML API.
:return: the path for MDANSE HTML documentation
:rtype: str
'''
return os.path.join(self.package_directory(), 'Doc', 'Help')
return os.path.join(self.package_directory(), 'Doc', 'api','html')
def help_path(self):
'''
Returns the path for MDANSE HTML help.
:return: the path for MDANSE HTML documentation
:rtype: str
'''
return os.path.join(self.package_directory(), 'Doc', 'help','html')
def local_mmtk_database_directory(self):
'''
......
......@@ -161,35 +161,106 @@ SCRIPTS.append(os.path.join(SCRIPTS_PATH,'mdanse'))
#################################
import sphinx.apidoc
from sphinx.setup_command import BuildDoc as _BuildDoc
import sphinx.setup_command
class BuildDoc(_BuildDoc):
class BuildDoc(sphinx.setup_command.BuildDoc):
user_options = sphinx.setup_command.BuildDoc.user_options + [('doctype=',None,'specify the type of documentation to build ("api" or "help")'),]
def initialize_options(self):
sphinx.setup_command.BuildDoc.initialize_options(self)
self.doctype='api'
def run(self):
build = self.get_finalized_command('build')
# sys.path.insert(0, os.path.abspath(build.build_lib))
build = self.get_finalized_command('build')
# metadata contains information supplied in setup()
buildDir = os.path.abspath(build.build_lib)
sphinxDir = os.path.join(build.build_base,'sphinx',self.doctype)
sys.path.insert(0,buildDir)
metadata = self.distribution.metadata
# Run sphinx by calling the main method, '--full' also adds a conf.py
sphinx.apidoc.main(['', '-F','--separate', '-H', metadata.name, '-A', metadata.author,
'-V', metadata.version, '-R', metadata.version,
'-o', 'sphinx_temp_rst', os.path.join(os.path.abspath(build.build_lib),'MDANSE'),os.path.join(os.path.abspath(build.build_lib),'MDANSE','Externals')])
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')])
import shutil
shutil.copy(os.path.join('Doc','conf.py'),'sphinx_temp_rst')
shutil.copy(os.path.join('Doc','mdanse_logo.png'),os.path.join('sphinx_temp_rst','_static'))
shutil.copy(os.path.join('Doc','layout.html'),os.path.join('sphinx_temp_rst','_templates'))
shutil.copy(os.path.join('Doc','conf_%s.py' % self.doctype),os.path.join(sphinxDir,'conf.py'))
shutil.copy(os.path.join('Doc','mdanse_logo.png'),os.path.join(sphinxDir,'_static'))
shutil.copy(os.path.join('Doc','layout.html'),os.path.join(sphinxDir,'_templates'))
self.source_dir = 'sphinx_temp_rst'
# The directory where the rst files are located.
self.source_dir = sphinxDir
# The directory where the conf.py file is located.
self.config_dir = self.source_dir
self.build_dir = os.path.join(os.path.abspath(build.build_lib),'MDANSE','Doc')
# The directory where the documentation will be built
self.build_dir = os.path.join(buildDir,'MDANSE','Doc',self.doctype)
self.finalize_options()
try:
_BuildDoc.run(self)
sphinx.setup_command.BuildDoc.run(self)
except UnicodeDecodeError:
print >>sys.stderr, "ERROR: unable to build documentation because Sphinx do not handle source path with non-ASCII characters. Please try to move the source package to another location (path with *only* ASCII characters)."
sys.path.pop(0)
class BuildHelp(sphinx.setup_command.BuildDoc):
def run(self):
build = self.get_finalized_command('build')
buildDir = os.path.abspath(build.build_lib)
HelpDir = os.path.join(build.build_base,'sphinx','Help')
sys.path.insert(0,buildDir)
metadata = self.distribution.metadata
sphinx.apidoc.main(['',
'-F',
'--separate',
'-d', '5',
'-H', metadata.name,
'-A', metadata.author,
'-V', metadata.version,
'-R', metadata.version,
'-o', HelpDir,
os.path.join(buildDir,'MDANSE'),
os.path.join(buildDir,'MDANSE','Externals')])
import shutil
shutil.copy(os.path.join('Doc','conf_help.py'),os.path.join(HelpDir,'conf.py'))
shutil.copy(os.path.join('Doc','mdanse_logo.png'),os.path.join(HelpDir,'_static'))
shutil.copy(os.path.join('Doc','layout.html'),os.path.join(HelpDir,'_templates'))
# The directory where the rst files are located.
self.source_dir = HelpDir
# The directory where the conf.py file is located.
self.config_dir = self.source_dir
# The directory where the documentation will be built
self.build_dir = os.path.join(buildDir,'MDANSE','Doc','Help')
try:
sphinx.setup_command.BuildDoc.run(self)
except UnicodeDecodeError:
print >>sys.stderr, "ERROR: unable to build documentation because Sphinx do not handle source path with non-ASCII characters. Please try to move the source package to another location (path with *only* ASCII characters)."
sys.path.pop(0)
#################################
......@@ -265,7 +336,7 @@ CMDCLASS = {'build_ext' : build_ext,
'build' : ModifiedBuild,
'build_py' : ModifiedBuildPy,
'build_scripts' : ModifiedBuildScripts,
'build_doc' : BuildDoc}
'build_doc' : BuildDoc}
#################################
# The setup section
......@@ -296,4 +367,5 @@ subunits can be studied.
ext_modules = EXTENSIONS,
scripts = SCRIPTS,
cmdclass = CMDCLASS,
command_options = {'build_doc' : {'builder':('setup.py','html')}}
)
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