Merge pull request #372 from ufo-kit/session-docs

Create session manual from docstring

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)
 

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

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
 =============
 

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