--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/pyams_user_guide/scripts/__init__.py Mon Dec 10 14:18:05 2018 +0100
@@ -0,0 +1,51 @@
+#!/var/local/env/pycharm/bin/python3.5
+import os
+from .beautydoc import main
+import shlex
+
+packages_pyams = [
+ 'pyams_alchemy',
+ 'pyams_cache',
+ 'pyams_catalog',
+ 'pyams_content',
+ 'pyams_content_es',
+ 'pyams_default_theme',
+ 'pyams_file',
+ 'pyams_form',
+ 'pyams_gis',
+ 'pyams_i18n',
+ 'pyams_ldap',
+ 'pyams_mail',
+ 'pyams_media',
+ 'pyams_notify',
+ 'pyams_notify_ws',
+ 'pyams_pagelet',
+ 'pyams_portal',
+ 'pyams_scheduler',
+ 'pyams_security',
+ 'pyams_sequence',
+ 'pyams_skin',
+ 'pyams_template',
+ 'pyams_thesaurus',
+ 'pyams_utils',
+ 'pyams_viewlet',
+ 'pyams_workflow',
+ 'pyams_zmi',
+ 'pyams_zmq',
+ 'pyams_zodbbrowser']
+
+path_project = '/var/local/src/pyams/'
+output_directory = '../src/source/api-doc/'
+
+def beautydoc():
+ """
+ Generate api-doc rst files.
+ Execute a custom sphinx-autodoc for each source code package in packages_pyams
+ :return: rst files
+ """
+ for p in packages_pyams:
+ directory = p
+ packages_pyams_source = os.path.join(*[path_project, p, 'src', directory])
+ outputdir = os.path.join(output_directory, directory)
+ # Command line
+ main(shlex.split('-f -T -M --maxdepth=2 -o {} {}'.format(outputdir, packages_pyams_source)))
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/pyams_user_guide/scripts/beautydoc.py Mon Dec 10 14:18:05 2018 +0100
@@ -0,0 +1,197 @@
+#!/var/local/env/pycharm/bin/python3.5
+from sphinx.ext.apidoc import *
+import sphinx.ext.apidoc as sp
+import sys
+
+sys.path[0:0] = [
+ '/var/local/src/pyams/pyams_alchemy/src',
+ '/var/local/src/pyams/pyams_cache/src',
+ '/var/local/src/pyams/pyams_catalog/src',
+ '/var/local/src/pyams/pyams_content/src',
+ '/var/local/src/pyams/pyams_content_es/src',
+ '/var/local/src/pyams/pyams_default_theme/src',
+ '/var/local/src/pyams/pyams_file/src',
+ '/var/local/src/pyams/pyams_form/src',
+ '/var/local/src/pyams/pyams_gis/src',
+ '/var/local/src/pyams/pyams_i18n/src',
+ '/var/local/src/pyams/pyams_ldap/src',
+ '/var/local/src/pyams/pyams_mail/src',
+ '/var/local/src/pyams/pyams_media/src',
+ '/var/local/src/pyams/pyams_notify/src',
+ '/var/local/src/pyams/pyams_notify_ws/src',
+ '/var/local/src/pyams/pyams_pagelet/src',
+ '/var/local/src/pyams/pyams_portal/src',
+ '/var/local/src/pyams/pyams_scheduler/src',
+ '/var/local/src/pyams/pyams_security/src',
+ '/var/local/src/pyams/pyams_sequence/src',
+ '/var/local/src/pyams/pyams_skin/src',
+ '/var/local/src/pyams/pyams_template/src',
+ '/var/local/src/pyams/pyams_thesaurus/src',
+ '/var/local/src/pyams/pyams_utils/src',
+ '/var/local/src/pyams/pyams_viewlet/src',
+ '/var/local/src/pyams/pyams_workflow/src',
+ '/var/local/src/pyams/pyams_zmi/src',
+ '/var/local/src/pyams/pyams_zmq/src',
+ '/var/local/src/pyams/pyams_zodbbrowser/src',
+ '/var/local/env/pycharm/lib/python3.5/site-packages',
+ ]
+
+
+def makename(package, module):
+ # type: (unicode, unicode) -> unicode
+ """Join package and module with a dot."""
+ # Both package and module can be None/empty.
+ if package:
+ name = package
+ if module:
+ name += '.' + module
+ else:
+ name = module
+ return name
+
+
+def format_heading(level, text, escape=True):
+ # type: (int, unicode, bool) -> unicode
+ """Create a heading of <level> [1, 2 or 3 supported]."""
+ if escape:
+ text = rst.escape(text)
+ underlining = ['=','-','~', '+', ][level - 1] * len(text)
+ return '%s\n%s\n\n' % (text, underlining)
+
+
+def format_directive(module, package=None):
+ # type: (unicode, unicode) -> unicode
+ """Create the automodule directive and add the options."""
+ directive = '.. automodule:: %s\n' % makename(package, module)
+ for option in OPTIONS:
+ directive += ' :%s:\n' % option
+ return directive
+
+
+def create_module_file(package, module, opts):
+ # type: (unicode, unicode, Any) -> None
+ """Build the text of the file and write the file."""
+ if not opts.noheadings:
+ text = format_heading(1, '%s module' % module)
+ else:
+ text = ''
+ # text += format_heading(2, ':mod:`%s` Module' % module)
+ text += format_directive(module, package)
+ write_file(makename(package, module), text, opts)
+
+
+def format_submodule(module):
+ # type: (unicode, unicode, Any) -> unicode
+ """Reformat submodule title"""
+ modulelist = module.split('.')
+ sub = modulelist.pop()
+ modulelist.append('\ ``' + sub + '``')
+ if modulelist:
+ module = '.'.join(modulelist)
+
+ return module
+
+
+def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace, excludes=[]): # NOQA
+ # type: (unicode, unicode, unicode, List[unicode], Any, List[unicode], bool, List[unicode]) -> None # NOQA
+ """Build the text of the file and write the file."""
+ myname = makename(master_package, subroot)
+ text ='.. _%s:\n\n' % myname
+ text += format_heading(1, ('\ :mod:`%s` package |package| ' if not is_namespace else "%s namespace")
+ % myname, escape=False)
+
+
+ #text += format_heading(1, ('%s package' if not is_namespace else "%s namespace")
+ # % makename(master_package, subroot))
+
+ if opts.modulefirst and not is_namespace:
+ text += format_directive(subroot, master_package)
+ text += '\n'
+
+ # build a list of directories that are szvpackages (contain an INITPY file)
+ # and also checks the INITPY file is not empty, or there are other python
+ # source files in that folder.
+ # (depending on settings - but shall_skip() takes care of that)
+ subs = [sub for sub in subs if not
+ shall_skip(path.join(root, sub, INITPY), opts, excludes)]
+ # if there are some package directories, add a TOC for theses subpackages
+ if subs:
+ text += format_heading(2, 'Subpackages')
+ text += '.. toctree::\n\n'
+ for sub in subs:
+ text += ' %s.%s\n' % (makename(master_package, subroot), sub)
+ text += '\n'
+
+ submods = [path.splitext(sub)[0] for sub in py_files
+ if not shall_skip(path.join(root, sub), opts, excludes) and
+ sub != INITPY]
+ if submods:
+ #text += format_heading(2, 'Submodules')
+ if opts.separatemodules:
+ text += '.. toctree::\n'
+ text += ' :maxdepth: %s\n\n' % opts.maxdepth
+ for submod in submods:
+ modfile = makename(master_package, makename(subroot, submod))
+ text += ' %s\n' % modfile
+
+ # generate separate file for this module
+ if not opts.noheadings:
+ filetext = format_heading(2, '%s' % format_submodule(modfile), escape=False)
+ else:
+ filetext = ''
+ filetext += format_directive(makename(subroot, submod),
+ master_package)
+ write_file(modfile, filetext, opts)
+ else:
+ for submod in submods:
+ modfile = makename(master_package, makename(subroot, submod))
+ if not opts.noheadings:
+ text += format_heading(2, '%s' % format_submodule(modfile), escape=False)
+ text += format_directive(makename(subroot, submod),
+ master_package)
+ text += '\n'
+ text += '\n'
+
+ if not opts.modulefirst and not is_namespace:
+ text += format_heading(2, 'Module contents')
+ text += format_directive(subroot, master_package)
+
+ # if there are some package directories, add a TOC for theses subpackages
+ if subs:
+ text += format_heading(2, 'Subpackages')
+ text += '.. toctree::\n\n'
+ for sub in subs:
+ text += ' %s.%s\n' % (makename(master_package, subroot), sub)
+ text += '\n'
+ text += '\n.. |package| unicode:: 0x229e\n'
+ write_file(makename(master_package, subroot), text, opts)
+
+
+def create_modules_toc_file(modules, opts, name='modules'):
+ # type: (List[unicode], Any, unicode) -> None
+ """Create the module's index."""
+ text = format_heading(2, '%s' % opts.header, escape=False)
+ text += '.. toctree::\n'
+ text += ' :maxdepth: %s\n\n' % opts.maxdepth
+
+ modules.sort()
+ prev_module = '' # type: unicode
+ for module in modules:
+ # look if the module is a subpackage and, if yes, ignore it
+ if module.startswith(prev_module + '.'):
+ continue
+ prev_module = module
+ text += ' %s\n' % module
+
+ write_file(name, text, opts)
+
+
+sp.makename = makename
+sp.create_modules_toc_file = create_modules_toc_file
+sp.create_package_file = create_package_file
+sp.format_heading = format_heading
+
+
+if __name__ == '__main__':
+
+ sys.exit(sphinx.ext.apidoc.main())