def generate_docs(self, template, formatter, highlighter, outdir): """ Generates and writes the documentation for the source file. If outdir is false, this will return the generated document. Otherwise it returns None. """ log.info('Generating docs for %s', self.fname) try: if outdir: outname = utils.destination(self.fname, outdir) + template.ext destdir = os.path.dirname(outname) if not os.path.isdir(destdir): os.makedirs(destdir) f = open(outname, 'w') else: f = StringIO() for line in template.generate_docs(self.format_sections(formatter, highlighter)): f.write(line) log.info('Documentation written for %s', self.fname) if not outdir: result = f.getvalue() else: result = None finally: f.close() return result
def test_destination(): """Test destination calculations.""" test_files = [ 'test', 'test.xyz', os.path.join('..', 'test.xyz'), os.path.join('subdir', 'test.xyz') ] test_dirs = [ None, 'dir', os.path.join('dir', 'dir'), os.path.join('..', 'dir'), ] testcases = itertools.product(test_files, test_dirs) for case in testcases: destination = utils.destination(*case) if case[1]: assert destination.endswith('test') else: assert destination == case[0] if not case[0].startswith('..') and case[1]: assert destination.startswith(case[1])
def main(): """ The command-line entry point. ###Commandline Arguments -d --directory : The directory to write documentation to. If this is a false value, documentation will be printed to stdout. -l --language : Force files to be interpreted as a given language. The string given must match a <name> key from the parsed languages. src : List of all source files to generate documentation for. """ logging.info('Parsing commandline arguments') parser = argparse.ArgumentParser( description='Generate documentation from sourcecode') parser.add_argument( '-d', '--directory', action='store', type=str, default=None, help='Output directory, writes to stdout if unspecified') parser.add_argument( '-l', '--language', action='store', type=str, default=None, help='Force the language for the given files') parser.add_argument( 'src', action='store', type=str, nargs='+', default=None, help='Files to generate documentation for') # Filter out arguments that weren't actually passed on the commandline args = parser.parse_args().__dict__.items() args = dict((k, v) for k, v in args if v is not None) logging.debug('Parsed args: %s', args) """ ###Settings directory : Writes documentation to stdout by default template : The minimal [tmp_basic](/pycclone/docs/templates/tmp_basic.html) template is used by default. formatter : The included [markdown formatter](/pycclone/docs/formatters/fmt_markdown.html) is used by default. highlighter : The included [pygments highlighter](/pycclone/docs/highlighters/hlt_pygments.html) is used by default. The `<plugin>_args` settings are specific to the plugin used and passed **as is** to the plugin's `__init__` method. See that plugin's documentation for details. """ settings = { 'directory': None, 'template': 'tmp_basic', 'formatter': 'fmt_markdown', 'highlighter': 'hlt_pygments', 'template_args': {}, 'formatter_args': {}, 'highlighter_args': { 'lexer': {}, 'formatter': {} }, } if os.path.isfile(pycclone.SETTINGSFILE): with open(pycclone.SETTINGSFILE, 'r') as f: settings.update(json.loads(f.read())) settings.update(args) logging.debug('Parsed settings: %s', settings) # Get the modules requested. template = get_template(settings['template']) template = template.Template(**settings['template_args']) formatter = get_formatter(settings['formatter']) formatter = formatter.Formatter(**settings['formatter_args']) highlighter = get_highlighter(settings['highlighter']) highlighter = highlighter.Highlighter(**settings['highlighter_args']) # Setup the output directory if settings['directory']: if not os.path.isdir(settings['directory']): os.makedirs(settings['directory']) template.copy_static(settings['directory']) highlighter.copy_static(settings['directory']) # Tell utils.destination which parent dirs to ignore when recreating # the directory structure. utils.ROOT = os.path.dirname(os.path.commonprefix(settings['src'])) destination = lambda x: utils.destination(x, settings['directory']) outfiles = [destination(x) for x in settings['src']] template.preprocess(outfiles) for src in settings['src']: result = Source(src).generate_docs( template, formatter, highlighter, settings['directory']) if result: sys.stdout.write('\n%s\n' % src) sys.stdout.write(result)