From ed95397da2568640af13114042ba434ddda586e6 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Wed, 30 Jan 2019 17:16:11 +0000 Subject: [PATCH] obsolete: old documentation configuration --- bin/cylc-documentation | 89 ++++++--------------- doc/src/appendices/site-user-config-ref.rst | 72 ++--------------- lib/cylc/cfgspec/globalcfg.py | 31 ++++--- lib/cylc/gui/app_gcylc.py | 37 +-------- 4 files changed, 54 insertions(+), 175 deletions(-) diff --git a/bin/cylc-documentation b/bin/cylc-documentation index d56f98195b9..0a9661d4e85 100755 --- a/bin/cylc-documentation +++ b/bin/cylc-documentation @@ -20,16 +20,15 @@ View documentation in the browser, as per Cylc global config. -% cylc doc [OPTIONS] - View local or internet [--www] Cylc documentation URLs. - +% cylc doc [--local] [OPTIONS] + Open the Cylc documentation. % cylc doc [-t TASK] SUITE View suite or task documentation, if URLs are specified in the suite. This -parses the suite definition to extract the requested URL. Note that suite -server programs also hold suite URLs for access from the Cylc GUI. + parses the suite definition to extract the requested URL. Note that suite + server programs also hold suite URLs for access from the Cylc GUI. Arguments: - [TARGET] File, URL, or suite name""" + [TARGET] File or suite name""" import sys @@ -40,8 +39,7 @@ for arg in sys.argv[1:]: sys.exit(0) import os -import re -from subprocess import call +from subprocess import check_call, CalledProcessError from optparse import OptionParser import cylc.flags @@ -53,13 +51,10 @@ def main(): parser = OptionParser(__doc__) parser.add_option( - "-g", "--guides", - help="Open the HTML (User & Suite Design) Guides directly.", - action="store_true", default=False, dest="guides") - - parser.add_option( - "-w", "--www", help="Open the cylc internet homepage", - action="store_true", default=False, dest="www") + "--local", + help=("Open the local documentation (if it has been built, see cylc " + "make-docs)."), + action="store_true", default=False, dest="local") parser.add_option( "-t", "--task", help="Browse task documentation URLs.", @@ -86,50 +81,23 @@ def main(): help="Print exception traceback on error.", action="store_true", default=False, dest="debug") - parser.add_option( - "--url", - help="URL to view in your configured browser.", - metavar="URL", default=None, action="store", dest="url") - (options, args) = parser.parse_args() cylc.flags.debug = options.debug - intranet_url = glbl_cfg().get(['documentation', 'urls', 'local index']) - internet_url = glbl_cfg().get(['documentation', 'urls', - 'internet homepage']) - html_file = glbl_cfg().get(['documentation', 'files', 'html user guides']) - html_viewer = glbl_cfg().get(['document viewers', 'html']) + viewer = glbl_cfg().get(['document viewers', 'html']) if len(args) == 0: # Cylc documentation. - if options.guides: - viewer = html_viewer - target = html_file - elif options.url: - viewer = html_viewer - target = options.url + if options.local: + target = glbl_cfg().get(['documentation', 'local']) else: - # HTML documentation index. - viewer = html_viewer - if options.www: - # Force internet. - if internet_url is not None: - target = internet_url - else: - sys.exit("ERROR: cylc internet URL not defined.") - elif intranet_url is not None: - # Intranet. - target = intranet_url - else: - # Open in file:// mode as a last resort. - print >> sys.stderr, ("WARNING: cylc intranet URL not " - "defined, trying file mode.") - target = html_file + target = glbl_cfg().get(['documentation', 'online']) + if target is None: + sys.exit("ERROR: no url defined, see the [documentation][%s'] " + "global configuration" % ( + 'local' if options.local else 'online')) elif len(args) == 1: # Suite or task documentation. - if options.guides or options.www: - print >> sys.stderr, ("(Note: --guides and --www are ignored for " - "suite documentation).") suite = args[0] if options.task_name: # Task documentation. @@ -150,31 +118,20 @@ def main(): else: sys.exit("ERROR: No URL defined for %s." % suite) target = stdout[0] - viewer = html_viewer else: parser.error("Too many arguments.") - if target in html_file and not os.path.isfile(target): - sys.exit("ERROR, file not found: %s (see your cylc admin)" % target) - - # viewer may have spaces (e.g. 'firefox --no-remote'): - command = '%s %s' % (viewer, target) - command_list = re.split(' ', command) - if options.stdout: print target sys.exit(0) try: - retcode = call(command_list, stdin=open(os.devnull)) - except OSError: + retcode = check_call( + # viewer may have spaces (e.g. 'firefox --no-remote'): + ('%s %s' % (viewer, target)).split(' '), stdin=open(os.devnull)) + except CalledProcessError: print >> sys.stderr, 'ERROR, failed to execute: %s' % command - if cylc.flags.debug: - raise - else: - if retcode != 0: - print >> sys.stderr, 'ERROR, command failed: %s' % command - sys.exit(retcode) + raise if __name__ == "__main__": diff --git a/doc/src/appendices/site-user-config-ref.rst b/doc/src/appendices/site-user-config-ref.rst index 09af6c80d75..cc89e97c108 100644 --- a/doc/src/appendices/site-user-config-ref.rst +++ b/doc/src/appendices/site-user-config-ref.rst @@ -179,57 +179,18 @@ Suite event logs are rolled over when they reach this file size. Documentation locations for the ``cylc doc`` command and gcylc Help menus. - -[documentation] ``->`` [[files]] +[documentation] ``->`` [[online]] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -File locations of documentation held locally on the cylc host server. - - -[documentation] ``->`` [[files]] ``->`` html index -"""""""""""""""""""""""""""""""""""""""""""""""""" - -File location of the main cylc documentation index. - -- *type*: string -- *default*: ``/doc/index.html`` - - -[documentation] ``->`` [[files]] ``->`` pdf user guide -"""""""""""""""""""""""""""""""""""""""""""""""""""""" - -File location of the cylc User Guide, PDF version. - -- *type*: string -- *default*: ``/doc/cug-pdf.pdf`` - - -[documentation] ``->`` [[files]] ``->`` multi-page html user guide -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -File location of the cylc User Guide, multi-page HTML version. - -- *type*: string -- *default*: ``/doc/html/multi/cug-html.html`` - - -[documentation] ``->`` [[files]] ``->`` single-page html user guide -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -File location of the cylc User Guide, single-page HTML version. +URL of the online cylc documentation. -- *type*: string -- *default*: ``/doc/html/single/cug-html.html`` - - -[documentation] ``->`` [[urls]] -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Online documentation URLs. +[documentation] ``->`` [[local]] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Path where the Cylc documentation will appear if built locally. -[documentation] ``->`` [[urls]] ``->`` internet homepage -"""""""""""""""""""""""""""""""""""""""""""""""""""""""" +[documentation] ``->`` [[cylc homepage]] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ URL of the cylc internet homepage, with links to documentation for the latest official release. @@ -238,30 +199,11 @@ latest official release. - *default*: http://cylc.github.com/cylc/ -[documentation] ``->`` [[urls]] ``->`` local index -"""""""""""""""""""""""""""""""""""""""""""""""""" - -Local intranet URL of the main cylc documentation index. - -- *type*: string -- *default*: (none) - - [document viewers] ------------------ PDF and HTML viewers can be launched by cylc to view the documentation. - -[document viewers] ``->`` pdf -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Your preferred PDF viewer program. - -- *type*: string -- *default*: evince - - [document viewers] ``->`` html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/lib/cylc/cfgspec/globalcfg.py b/lib/cylc/cfgspec/globalcfg.py index 2fb5b340e30..1ff7f368053 100644 --- a/lib/cylc/cfgspec/globalcfg.py +++ b/lib/cylc/cfgspec/globalcfg.py @@ -88,20 +88,16 @@ }, 'documentation': { - 'files': { - 'html user guides': [ - VDR.V_STRING, '$CYLC_DIR/doc/built-sphinx/index.html'], - }, - 'urls': { - 'internet homepage': [VDR.V_STRING, 'http://cylc.github.io/cylc/'], - 'local index': [VDR.V_STRING], - }, + 'local': [VDR.V_STRING, '$CYLC_DIR/doc/built-sphinx/index.html'], + 'online': [VDR.V_STRING, + 'http://cylc.github.io/cylc/doc/built-sphinx/index.html'], + 'cylc homepage': [VDR.V_STRING, 'http://cylc.github.io/cylc/'], }, 'document viewers': { - 'pdf': [VDR.V_STRING, 'evince'], 'html': [VDR.V_STRING, 'firefox'], }, + 'editors': { 'terminal': [VDR.V_STRING, 'vim'], 'gui': [VDR.V_STRING, 'gvim -f'], @@ -278,6 +274,19 @@ def upg(cfg, descr): u.obsolete('8.0.0', ['communication', 'base port']) u.obsolete('8.0.0', ['suite host scanning'], ['suite servers']) u.obsolete('8.0.0', ['suite servers', 'hosts']) + u.deprecate('8.0.0', + ['documentation', 'files', 'html index'], + ['documentation', 'local']) + u.deprecate('7.8.1', + ['documentation', 'files', 'multi-page html user guide'], + ['documentation', 'local']) + u.deprecate('8.0.0', + ['documentation', 'urls', 'internet homepage'], + ['documentation', 'cylc homepage']) + u.obsolete('7.8.1', ['documentation', 'local index']) + u.obsolete('7.8.1', ['documentation', 'files', 'pdf user guide']) + u.obsolete('7.8.1', ['documentation', 'files', + 'single-page html user guide']) for batch_sys_name in ['loadleveler', 'lsf', 'pbs', 'sge', 'slurm']: u.obsolete( @@ -578,8 +587,8 @@ def transform(self): # Expand environment variables and ~user in LOCAL file paths. if 'HOME' not in os.environ: os.environ['HOME'] = self._HOME - for key, val in cfg['documentation']['files'].items(): - cfg['documentation']['files'][key] = os.path.expandvars(val) + cfg['documentation']['local'] = os.path.expandvars( + cfg['documentation']['local']) for key, val in cfg['hosts']['localhost'].items(): if val and 'directory' in key: cfg['hosts']['localhost'][key] = os.path.expandvars(val) diff --git a/lib/cylc/gui/app_gcylc.py b/lib/cylc/gui/app_gcylc.py index 2113cd4d6dd..52b7c4af37b 100644 --- a/lib/cylc/gui/app_gcylc.py +++ b/lib/cylc/gui/app_gcylc.py @@ -2635,40 +2635,11 @@ def create_main_menu(self): help_menu_root = gtk.MenuItem('_Help') help_menu_root.set_submenu(help_menu) - doc_menu = gtk.Menu() - doc_item = gtk.ImageMenuItem("_Documentation") - img = gtk.image_new_from_stock(gtk.STOCK_COPY, gtk.ICON_SIZE_MENU) - doc_item.set_image(img) - doc_item.set_submenu(doc_menu) - help_menu.append(doc_item) - - cug_html_item = gtk.ImageMenuItem('(file://) Documentation Index') + documentation_item = gtk.ImageMenuItem('(http://) Documentation') img = gtk.image_new_from_stock(gtk.STOCK_DND, gtk.ICON_SIZE_MENU) - cug_html_item.set_image(img) - doc_menu.append(cug_html_item) - cug_html_item.connect('activate', self.browse_doc) - - cug_pdf_item = gtk.ImageMenuItem('(file://) PDF User Guide') - img = gtk.image_new_from_stock(gtk.STOCK_EDIT, gtk.ICON_SIZE_MENU) - cug_pdf_item.set_image(img) - doc_menu.append(cug_pdf_item) - cug_pdf_item.connect('activate', self.browse_doc, '-p') - - doc_menu.append(gtk.SeparatorMenuItem()) - - if glbl_cfg().get(['documentation', 'urls', 'local index']): - cug_www_item = gtk.ImageMenuItem('(http://) Local Document Index') - img = gtk.image_new_from_stock(gtk.STOCK_JUMP_TO, - gtk.ICON_SIZE_MENU) - cug_www_item.set_image(img) - doc_menu.append(cug_www_item) - cug_www_item.connect('activate', self.browse_doc, '-x') - - cug_www_item = gtk.ImageMenuItem('(http://) _Internet Home Page') - img = gtk.image_new_from_stock(gtk.STOCK_JUMP_TO, gtk.ICON_SIZE_MENU) - cug_www_item.set_image(img) - doc_menu.append(cug_www_item) - cug_www_item.connect('activate', self.browse_doc, '-w') + documentation_item.set_image(img) + help_menu.append(documentation_item) + documentation_item.connect('activate', self.browse_doc) chelp_menu = gtk.ImageMenuItem('_Command Help') img = gtk.image_new_from_stock(gtk.STOCK_EXECUTE, gtk.ICON_SIZE_MENU)