SfePy NTC

Source code for sync_module_docs

#!/usr/bin/env python
"""
Synchronize the documentation files in a given directory ``doc_dir`` with the
actual state of the SfePy sources in ``top_dir``. Missing files are created,
files with no corresponding source file are removed, other files are left
untouched.

Notes
-----
The developer guide needs to be edited manually to reflect the changes.
"""
import sys
sys.path.append('.')
import os
import fnmatch
from optparse import OptionParser

from sfepy.base.base import output
from sfepy.base.ioutils import locate_files, edit_filename, ensure_path

usage = '%prog [options] doc_dir top_dir\n' + __doc__.rstrip()

omits = [
    '__init__.py',
    '__config__.py',
    'debug.py',
    'setup.py',
    'site_cfg.py',
    'site_cfg_template.py',
]

omits_pyx = [
    'lobatto_template.pyx',
]

doc_template = """%s
%s

.. automodule:: %s
   :members:
   :undoc-members:
"""

help = {
    'dry_run' :
    'only show what changes would be made',
}

[docs]def main(): parser = OptionParser(usage=usage, version='%prog') parser.add_option('-n', '--dry-run', action='store_true', dest='dry_run', default=False, help=help['dry_run']) options, args = parser.parse_args() if len(args) == 2: doc_dir, top_dir = [os.path.realpath(ii) for ii in args] else: parser.print_help(), return docs = set(ii for ii in locate_files('*.rst', root_dir=doc_dir)) sources = set(ii for ii in locate_files('*.py', root_dir=os.path.join(top_dir, 'sfepy')) if os.path.basename(ii) not in omits) sources.update(ii for ii in locate_files('*.pyx', root_dir=os.path.join(top_dir, 'sfepy')) if os.path.basename(ii) not in omits_pyx) scripts = set(ii for ii in locate_files('*.py', root_dir=os.path.join(top_dir, 'script')) if os.path.basename(ii) not in omits) top_scripts = set(os.path.realpath(ii) for ii in fnmatch.filter(os.listdir(top_dir), '*.py') if os.path.basename(ii) not in omits) all_sources = set() all_sources.update(sources, scripts, top_scripts) cwd = os.path.realpath(os.path.curdir) + os.path.sep output.prefix = 'smd:' output('removing unneeded rst files in "%s"...' % doc_dir) for doc in sorted(docs): aux = edit_filename(doc, new_ext='.py') src1 = os.path.normpath(aux.replace(doc_dir, top_dir)) aux = edit_filename(doc, new_ext='.pyx') src2 = os.path.normpath(aux.replace(doc_dir, top_dir)) if (src1 not in all_sources) and (src2 not in all_sources): output('remove: %s' % doc.replace(cwd, '')) if not options.dry_run: os.remove(doc) output('...done') output('creating missing rst files in "%s"...' % doc_dir) for src in sorted(all_sources): aux = edit_filename(src, new_ext='.rst') doc = os.path.normpath(aux.replace(top_dir, doc_dir)) if doc not in docs: output('create: %s' % doc.replace(cwd, '')) if not options.dry_run: mod_filename = src.replace(top_dir + os.path.sep, '') mod_name = mod_filename.replace(os.path.sep, '.') mod_name = edit_filename(mod_name, new_ext='') if mod_name.startswith('sfepy'): # Module. title = mod_name + ' module' else: # Script. title = mod_filename + ' script' mod_name = mod_name.split('.')[-1] underlines = '=' * len(title) contents = doc_template % (title, underlines, mod_name) ensure_path(doc) fd = open(doc, 'w') fd.write(contents) fd.close() output('...done')
if __name__ == '__main__': main()