diff --git a/bin/concert b/bin/concert index e19408f3d..001348c50 100644 --- a/bin/concert +++ b/bin/concert @@ -450,6 +450,35 @@ class StartCommand(Command): print(msg.format(exception)) +class DocsCommand(Command): + + """Create documentation of *session* docstring.""" + + def __init__(self): + opts = {'session': {'type': str, 'metavar': 'session'}} + super(DocsCommand, self).__init__('docs', opts) + + def run(self, session): + import subprocess + import shlex + + try: + subprocess.check_output(['pandoc', '-v']) + except OSError: + print("Please install pandoc and pdftex to generate docs.") + sys.exit(1) + + cs.exit_if_not_exists(session) + module = cs.load(session) + + if not module.__doc__: + print("No docstring in `{}' found".format(session)) + + cmd_line = shlex.split('pandoc -f markdown -t latex -o {}.pdf'.format(session)) + pandoc = subprocess.Popen(cmd_line, stdin=subprocess.PIPE) + pandoc.communicate(module.__doc__) + + def main(): parser = argparse.ArgumentParser() @@ -469,7 +498,8 @@ def main(): RemoveCommand(), ImportCommand(), ExportCommand(), - StartCommand()] + StartCommand(), + DocsCommand()] commands.extend(plugins) diff --git a/concert/session/management.py b/concert/session/management.py index 1c0c83bb8..c90a3442a 100644 --- a/concert/session/management.py +++ b/concert/session/management.py @@ -9,7 +9,12 @@ _CACHED_PATH = None -_SESSION_TEMPLATE = """\"\"\"This is session {doc}\"\"\" +_SESSION_TEMPLATE = """\"\"\"# *{doc}* session manual + +## Usage + +## Notes +\"\"\" import logging import concert diff --git a/docs/user/topics/shell.rst b/docs/user/topics/shell.rst index 656285b1c..2ec40adf1 100644 --- a/docs/user/topics/shell.rst +++ b/docs/user/topics/shell.rst @@ -30,6 +30,7 @@ help is shown:: rm Remove one or more sessions import Import an existing *session* export Export all sessions as a Zip archive + docs Create documentation of *session* docstring The tool is command-driven, that means you call it with a command as its first argument. To read command-specific help, use:: @@ -238,6 +239,23 @@ The quantities package is already loaded and named ``q``. Run the session as a script and do not launch a shell. +docs +---- + +.. program:: concert docs + +Create a PDF documentation for a session:: + + concert docs session-name + +Creates a PDF manual named *session-name.zip* with the contents taken from the +session's docstring. The docstring should be formatted in Markdown markup. + +.. note:: + + This requires an installation of Pandoc and PDFLaTeX. + + Remote access ============= diff --git a/extras/completion/concert.sh b/extras/completion/concert.sh index 3cb2138c0..4b01b518c 100644 --- a/extras/completion/concert.sh +++ b/extras/completion/concert.sh @@ -5,10 +5,10 @@ _concert() cur="${COMP_WORDS[COMP_CWORD]}" prev="${COMP_WORDS[COMP_CWORD-1]}" - opts="edit import export init log rm mv cp show start" + opts="edit import export init log rm mv cp show start docs" case "${prev}" in - init) + init|docs) local more=$(for x in `concert ${prev} --help | grep " --" - | awk '{ print $1 }'`; do echo ${x}; done) COMPREPLY=($(compgen -W "${more}" -- ${cur})) return 0