obsolete: old documentation configuration

cylc · Jan 31, 2019 · ed95397 · ed95397
1 parent 8339155
commit ed95397
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 175 deletions.
diff --git 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
@@ -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*: ``<cylc-dir>/doc/index.html``
-
-
-[documentation] ``->`` [[files]] ``->`` pdf user guide
-""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-File location of the cylc User Guide, PDF version.
-
-- *type*: string
-- *default*: ``<cylc-dir>/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*: ``<cylc-dir>/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*: ``<cylc-dir>/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
@@ -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
@@ -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)