Merge pull request #2200 from oliver-sanders/rose-user-guide-pdf

doc: pdf output

.travis.yml

@@ -23,7 +23,8 @@ install:
         sudo apt-get install -y at build-essential gfortran heirloom-mailx
         pcregrep python-pip python-dev graphviz libgraphviz-dev python-jinja2
         python-sqlalchemy libxml-parser-perl libconfig-inifiles-perl
-        libdbi-perl libdbd-sqlite3-perl
+        libdbi-perl libdbd-sqlite3-perl latexmk texlive
+        texlive-generic-extra texlive-latex-extra texlive-fonts-recommended
     - pip install cherrypy Jinja2 requests sqlalchemy pyopenssl pycodestyle
     - pip install pygraphviz --install-option="--include-path=/usr/include/graphviz" --install-option="--library-path=/usr/lib/graphviz/"
     - sudo sh -c 'echo "deb http://opensource.wandisco.com/ubuntu `lsb_release -cs` svn19" >> /etc/apt/sources.list.d/subversion19.list'
@@ -41,4 +42,4 @@ jobs:
             (echo -e "\n\nRerunning Failed Tests...\n\n";
             rose test-battery -v --state=save,failed -j 5)
         - script: >
-            rose make-docs --venv --dev --strict clean linkcheck doctest html slides
+            rose make-docs --venv --dev --strict clean linkcheck doctest html slides latexpdf

sphinx/Makefile

@@ -19,7 +19,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext pdf slides
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -59,6 +59,10 @@ slides:
 	@echo
 	@echo "Build finished. The slide-html files are in $(BUILDDIR)/slides."
 
+pdf: latexpdf
+	python extract-pdf-documents.py "$(BUILDDIR)"
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/pdf."
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

sphinx/_static/js/versioning.js

@@ -25,12 +25,22 @@ $(document).ready(function() {
             // construct format selector
             var bui = ele.append($('<dl />'));
             $(bui).append($('<dt />').append('Formats'));
+            var href;
             for (let builder_for_version of versions[current_version].sort()) {
+                href = root_dir + current_version + '/' + builder_for_version +
+                       '/';
+                if (['html', 'slides'].indexOf(builder_for_version) >= 0) {
+                    // format has compatible document structure
+                    href += current_page_name + '.html';
+                } else {
+                    // structure different, link to the index.html page
+                    href += 'index.html';
+                }
+
+
                 $(bui).append($('<dd />')
                     .append($('<a />')
-                        .attr({'href': root_dir + current_version + '/' +
-                                       builder_for_version + '/' +
-                                       current_page_name})
+                        .attr({'href': href})
                         .append(builder_for_version)
                     )
                 );

sphinx/conf.py

@@ -36,6 +36,7 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.graphviz',
+    'sphinx.ext.imgconverter',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
@@ -110,17 +111,21 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-    'papersize': 'a4paper'
-    # 'preamble': '',  # Additional stuff for the LaTeX preamble.
+    'papersize': 'a4paper',
+    'maxlistdepth': 10  # Prevent "Too Deeply Nested" errors.
 }
 
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     ('index', 'rose-documentation.tex', 'Rose Documentation',
      'Metomi', 'manual'),
+    ('tutorial/cylc/index', 'cylc-tutorial.tex', 'Cylc Tutorial',
+     'Metomi', 'manual'),
+    ('tutorial/rose/index', 'rose-tutorial.tex', 'Rose Tutorial',
+     'Metomi', 'manual'),
 ]
-# latex_logo = None
+latex_logo = 'img/rose-logo.png'
 # If true, show page references after internal links.
 latex_show_pagerefs = True
 # If true, show URL addresses after external links.

sphinx/ext/rose_domain.py

@@ -261,6 +261,37 @@ def namespace_from_tokens(tokens):
     return ret
 
 
+TOKEN_ORDER = [
+    ('rose:file', 'rose:file'),
+    ('rose:app', 'rose:app'),
+    ('rose:conf-section', 'rose:conf'),
+    ('rose:conf', 'rose:conf')
+]
+
+def tokens_from_ref_context(ref_context):
+    """Extract a list of tokens from a ref_context dictionary.
+
+    Examples:
+        >>> tokens_from_ref_context({'rose:conf-section': '[bar]',
+        ...                          'rose:conf': 'baz',
+        ...                          'rose:file': 'foo'})
+        [('rose:file', 'foo'), ('rose:conf', '[bar]'), ('rose:conf', 'baz')]
+        >>> tokens_from_ref_context({'rose:conf-section': '[bar]',
+        ...                          'rose:conf': 'baz',
+        ...                          'rose:app': 'foo'})
+        [('rose:app', 'foo'), ('rose:conf', '[bar]'), ('rose:conf', 'baz')]
+    """
+    # Generate context namespace from ref_context.
+    ret = [(v, ref_context[k]) for k, v in TOKEN_ORDER if k in ref_context]
+    # Remove any duplicate items (happens for conf-sections where you
+    # may get {'rose:conf-section': '[foo]', 'rose:conf': '[foo]'}.
+    last = None
+    for item in list(ret):
+        if last is not None and item == last:
+            ret.remove(item)
+        last = item
+    return ret
+
 class RoseDirective(ObjectDescription):
     """Base class for implementing Rose objects.
 
@@ -627,8 +658,10 @@ class RoseXRefRole(XRefRole):
     This should be minimal."""
 
     def process_link(self, env, refnode, has_explicit_title, title, target):
-        if not has_explicit_title:
-            pass
+        # copy ref_context to the refnode so that we can access it in
+        # resolve_xref. Note that walking through the node tree to extract
+        # ref_context items appears only to work in the HTML buider.
+        refnode['ref_context'] = dict(env.ref_context)
         return title, target
 
 
@@ -706,24 +739,6 @@ def get_objects(self):
         for refname, (docname, type_) in list(self.data['objects'].items()):
             yield refname, refname, type_, docname, refname, 1
 
-    @staticmethod
-    def get_context_namespace(node):
-        """Extract the namespace from a content node.
-
-        Walks up the node hierarchy from the current node collecting
-        ref_context information as it does. See ``RoseDirective.run`` for
-        information on how this context comes to reside in the node.
-        """
-        context_namespace = []
-        while hasattr(node, 'parent'):
-            if hasattr(node, 'ref_context'):
-                # Each ref_context dict should contain only one entry (for
-                # now).
-                context_namespace.append(node.ref_context.items()[0])
-            node = node.parent
-        context_namespace.reverse()
-        return context_namespace
-
     def resolve_xref(self, env, fromdocname, builder, typ, target, node,
                      contnode):
         """Associate a reference with a documented object.
@@ -770,7 +785,7 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node,
                 namespace = 'rose:%s:%s' % (typ, target)
             else:
                 # Target is not a root config - path is relative.
-                context_namespace = self.get_context_namespace(node)
+                context_namespace = tokens_from_ref_context(node['ref_context'])
                 if not context_namespace:
                     LOGGER.warning(
                         'Relative reference requires local context ' +

sphinx/extract-pdf-documents.py

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+# -----------------------------------------------------------------------------
+# (C) British Crown Copyright 2012-8 Met Office.
+#
+# This file is part of Rose, a framework for meteorological suites.
+#
+# Rose is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Rose is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Rose. If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------
+"""Script for extracting PDF documents from a Sphinx LaTeX build.
+
+* Copies PDF documents from the ``latex`` build directory to a ``pdf`` folder.
+* Creates an HTML index of these documents.
+
+"""
+
+import errno
+import os
+import shutil
+import sys
+
+import conf
+
+
+try:
+    BUILD_DIR = sys.argv[1]
+except IndexError:
+    sys.exit('usage: extract-pdf-documents BUILD_DIR')
+LATEX_DIR = os.path.join(BUILD_DIR, 'latex')
+PDF_DIR = os.path.join(BUILD_DIR, 'pdf')
+try:
+    os.mkdir(PDF_DIR)
+except OSError as exc:
+    if exc.errno == errno.EEXIST:
+        # directory exists -> no further action required
+        pass
+    else:
+        # meaningful os error -> raise
+        raise
+
+# the index html file
+html = (
+    '<!DOCTYPE html>'
+    '<html>'
+    '<head>'
+    '<title>Rose Documentation - PDF Documents</title>'
+    '</head>'
+    '<body>'
+    '<h1>Rose Documentation - PDF Documents</h1>'
+    '<ul>'
+)
+
+# loop over PDF documents defined in the Sphinx configuration file
+for file_name, document_name in (x[1:3] for x in conf.latex_documents):
+    # move PDF document into the pdf directory
+    file_name = file_name.replace('.tex', '.pdf')
+    os.rename(
+        os.path.join(LATEX_DIR, file_name),
+        os.path.join(PDF_DIR, file_name)
+    )
+    # add an index entry for this document
+    html += (
+        '<li>'
+        '<a href="%s">%s</a>'
+        '</li>' % (file_name, document_name)
+    )
+
+html += (
+    '</ul>'
+    '</body>'
+    '</html>'
+)
+
+# write index file
+with open(os.path.join(PDF_DIR, 'index.html'), 'w+') as index:
+    index.write(html)
+
+# remove now un-necessary latex directory
+shutil.rmtree(LATEX_DIR)