Permalink
Browse files

Added UPyUG presentation for Sphinx

  • Loading branch information...
1 parent 2946c42 commit 2d7ae59813958f773fd0e9dd97013f2e9e4c90ab @whiteinge committed Feb 11, 2011
@@ -0,0 +1,186 @@
+======================
+Utah Python User Group
+======================
+Sphinx: Python Documentation Generator
+--------------------------------------
+
+:Author: Seth House <seth@eseth.com>
+:Date: 2011-02-10
+
+.. include:: <s5defs.txt>
+
+Background
+==========
+
+http://docs.python.org/
+
+reStructuredText
+================
+
+.. class:: handout
+
+ “The primary goal of reStructuredText is to define a markup syntax for use
+ in Python docstrings and other documentation domains, that is readable and
+ simple, yet powerful enough for non-trivial use. The intended purpose of
+ the reStructuredText markup is twofold:
+
+ * the establishment of a set of standard conventions allowing the
+ expression of structure within plaintext, and
+ * the conversion of such documents into useful structured data formats.
+
+ The secondary goal of reStructuredText is to be accepted by the Python
+ community (by way of being blessed by PythonLabs and the BDFL [1]) as a
+ standard for Python inline documentation (possibly one of several
+ standards, to account for taste).”
+
+ — http://docutils.sourceforge.net/docs/ref/rst/introduction.html#goals
+
+http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+
+reStructuredText
+================
+
+* rst2html
+* rst2latex
+* rst2man
+* rst2odt
+* rst2s5
+* rst2xml
+
+reStructuredText
+================
+
+* http://rst2a.com/
+* http://docutils.sourceforge.net/docs/user/links.html
+
+Docutils
+========
+
+.. class:: handout
+
+ By far the most powerful and flexible of the lightweight markup languages.
+
+Parsing and translating suite
+
+Docutils
+========
+
+::
+
+ +---------------------------+
+ | Docutils: |
+ | docutils.core.Publisher, |
+ | docutils.core.publish_*() |
+ +---------------------------+
+ / | \
+ +--------+ +-------------+ +--------+
+ | READER | ----> | TRANSFORMER | ====> | WRITER |
+ +--------+ +-------------+ +--------+
+ / \\ |
+ +-------+ +--------+ +--------+
+ | INPUT | | PARSER | | OUTPUT |
+ +-------+ +--------+ +--------+
+
+Sphinx
+======
+
+.. class:: tiny
+
+ * StandaloneHTMLBuilder
+ * DirectoryHTMLBuilder
+ * SingleFileHTMLBuilder
+ * HTMLHelpBuilder (Microsoft CHM)
+
+ * QtHelpBuilder (KDE)
+ * DevhelpBuilder (Gnome)
+
+ * EpubBuilder
+ * LaTeXBuilder
+ * TextBuilder
+ * ManualPageBuilder
+ * SerializingHTMLBuilder (pickle, simplejson, phpserialize)
+ * PickleHTMLBuilder
+ * JSONHTMLBuilder
+ * ChangesBuilder (versionadded, versionchanged and deprecated)
+ * CheckExternalLinksBuilder
+
+Sphinx
+======
+
+.. code-block:: bash
+
+ % sphinx-quickstart
+
+Sphinx
+======
+
+Docutils additions: “semantic markup and automatic links for functions,
+classes, citations, glossary terms and similar pieces of information”
+
+* Extensive cross-references
+* Automatic indices: general index as well as a module index
+
+ * TOC Tree
+ * Index
+ * Glossary
+
+* Extensions
+
+Domains
+=======
+
+* Python
+* C
+* C++
+* JavaScript
+* reStructuredText
+* Ruby (contrib)
+* Erlang (contrib)
+
+https://bitbucket.org/birkenfeld/sphinx-contrib/src
+
+Domains
+=======
+
+.. code-block:: rst
+
+ .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
+
+Domains
+=======
+
+.. code-block:: rst
+
+ .. js:function:: $.getJSON(href, callback[, errback])
+
+ :param string href: An URI to the location of the resource.
+ :param callback: Get's called with the object.
+ :param errback:
+ Get's called in case the request fails. And a lot of other
+ text so we need multiple lines
+ :throws SomeError: For whatever reason in that case.
+ :returns: Something
+
+HTML templating / theming
+=========================
+
+* Jinja
+* Themes
+
+Extensions
+==========
+
+* Builders
+* Domains
+* Nodes
+* Directives
+* Roles
+* Crossrefs
+* Transforms
+
+Extensions
+==========
+
+Core events
+
+http://sphinx.pocoo.org/ext/tutorial.html#build-phases
@@ -0,0 +1,82 @@
+#!/usr/bin/python
+
+# Author: Chris Liechti
+# Contact: cliechti@gmx.net
+# Revision: $Revision$
+# Date: $Date$
+# Copyright: This module has been placed in the public domain.
+
+"""
+A minimal front end to the Docutils Publisher, producing HTML slides using
+the S5 template system.
+"""
+
+try:
+ import locale
+ locale.setlocale(locale.LC_ALL, '')
+except:
+ pass
+
+import pygments
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import get_formatter_by_name
+from docutils.parsers import rst
+from docutils import nodes
+
+def code_formatter(language, content):
+ lexer = get_lexer_by_name(language)
+ formatter = get_formatter_by_name('html', noclasses=True)
+ html = pygments.highlight(content, lexer, formatter)
+ return nodes.raw('', html, format='html')
+
+def code_role(name, rawtext, text, lineno, inliner, options={},
+ content=[]):
+ language = options.get('language')
+ if not language:
+ args = text.split(':', 1)
+ language = args[0]
+ if len(args) == 2:
+ text = args[1]
+ else:
+ text = ''
+ reference = code_formatter(language, text)
+ return [reference], []
+
+def code_block(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ """
+ Create a code-block directive for docutils.
+
+ Usage: .. code-block:: language
+
+ If the language can be syntax highlighted it will be.
+ """
+ language = arguments[0]
+ text = '\n'.join(content)
+ reference = code_formatter(language, text)
+ return [reference]
+
+# These are documented
+# at http://docutils.sourceforge.net/spec/howto/rst-directives.html.
+code_block.arguments = (
+ 1, # Number of required arguments.
+ 0, # Number of optional arguments.
+ 0) # True if final argument may contain whitespace.
+
+# A mapping from option name to conversion function.
+code_role.options = code_block.options = {
+ 'language' :
+ rst.directives.unchanged # Return the text argument, unchanged
+}
+code_block.content = 1 # True if content is allowed.
+# Register the directive with docutils.
+rst.directives.register_directive('code-block', code_block)
+rst.roles.register_local_role('code-block', code_role)
+
+
+from docutils.core import publish_cmdline, default_description
+
+description = ('Generates S5 (X)HTML slideshow documents from standalone '
+ 'reStructuredText sources. ' + default_description)
+
+publish_cmdline(writer_name='s5', description=description)
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -0,0 +1,24 @@
+/* This file has been placed in the public domain. */
+/* The following styles size, place, and layer the slide components.
+ Edit these if you want to change the overall slide layout.
+ The commented lines can be uncommented (and modified, if necessary)
+ to help you with the rearrangement process. */
+
+/* target = 1024x768 */
+
+div#header, div#footer, .slide {width: 100%; top: 0; left: 0;}
+div#footer {top: auto; bottom: 0; height: 2.5em; z-index: 5;}
+.slide {top: 0; width: 92%; padding: 1em 4% 0 4%; z-index: 2;}
+div#controls {left: 50%; bottom: 0; width: 50%; z-index: 100;}
+div#controls form {position: absolute; bottom: 0; right: 0; width: 100%;
+ margin: 0;}
+#currentSlide {position: absolute; width: 10%; left: 45%; bottom: 1em;
+ z-index: 10;}
+html>body #currentSlide {position: fixed;}
+
+/*
+div#header {background: #FCC;}
+div#footer {background: #CCF;}
+div#controls {background: #BBD;}
+div#currentSlide {background: #FFC;}
+*/
@@ -0,0 +1,42 @@
+<public:component>
+<public:attach event="onpropertychange" onevent="doFix()" />
+
+<script>
+
+// IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull http://www.twinhelix.com
+// This is licensed under the GNU LGPL, version 2.1 or later.
+
+// This must be a path to a blank image. That's all the configuration you need here.
+var blankImg = 'ui/small-white/blank.gif';
+
+var f = 'DXImageTransform.Microsoft.AlphaImageLoader';
+
+function filt(s, m) {
+ if (filters[f]) {
+ filters[f].enabled = s ? true : false;
+ if (s) with (filters[f]) { src = s; sizingMethod = m }
+ } else if (s) style.filter = 'progid:'+f+'(src="'+s+'",sizingMethod="'+m+'")';
+}
+
+function doFix() {
+ if ((parseFloat(navigator.userAgent.match(/MSIE (\S+)/)[1]) < 5.5) ||
+ (event && !/(background|src)/.test(event.propertyName))) return;
+
+ if (tagName == 'IMG') {
+ if ((/\.png$/i).test(src)) {
+ filt(src, 'image'); // was 'scale'
+ src = blankImg;
+ } else if (src.indexOf(blankImg) < 0) filt();
+ } else if (style.backgroundImage) {
+ if (style.backgroundImage.match(/^url[("']+(.*\.png)[)"']+$/i)) {
+ var s = RegExp.$1;
+ style.backgroundImage = '';
+ filt(s, 'crop');
+ } else filt();
+ }
+}
+
+doFix();
+
+</script>
+</public:component>
@@ -0,0 +1,8 @@
+/* This file has been placed in the public domain. */
+/* DO NOT CHANGE THESE unless you really want to break Opera Show */
+.slide {
+ visibility: visible !important;
+ position: static !important;
+ page-break-before: always;
+}
+#slide0 {page-break-before: avoid;}
@@ -0,0 +1,16 @@
+/* This file has been placed in the public domain. */
+/* Don't change this unless you want the layout stuff to show up in the
+ outline view! */
+
+.layout div, #footer *, #controlForm * {display: none;}
+#footer, #controls, #controlForm, #navLinks, #toggle {
+ display: block; visibility: visible; margin: 0; padding: 0;}
+#toggle {float: right; padding: 0.5em;}
+html>body #toggle {position: fixed; top: 0; right: 0;}
+
+/* making the outline look pretty-ish */
+
+#slide0 h1, #slide0 h2, #slide0 h3, #slide0 h4 {border: none; margin: 0;}
+#toggle {border: 1px solid; border-width: 0 0 1px 1px; background: #FFF;}
+
+.outline {display: inline ! important;}
Oops, something went wrong.

0 comments on commit 2d7ae59

Please sign in to comment.