Trying custom stuff

Author: rdunklau

.gitignore

@@ -9,3 +9,4 @@ sql/multicorn--*.sql
 /dist
 /results
 doc/_build
+doc/dist

doc/_static/css/custom.css

@@ -0,0 +1,3 @@
+body {
+  background-color: red;
+}

doc/conf.py

@@ -15,11 +15,15 @@
 import sys
 import os
 
+from sphinx.builders.html import StandaloneHTMLBuilder
+StandaloneHTMLBuilder.css_files = ["_static/css/custom.css"] + StandaloneHTMLBuilder.css_files
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../python/'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
@@ -35,6 +39,7 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'multicorn_directives'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -103,9 +108,17 @@
 
 # -- Options for HTML output ----------------------------------------------
 
+# on_rtd is whether we are on readthedocs.org
+import os
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -267,3 +280,16 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+rst_prolog = """
+:mailaddress: [email protected]
+:mailarchives: http://librelist.com/browser/multicorn
+:buglink: https://github.com/Kozea/Multicorn/issues
+:codelink: https://github.com/Kozea/Multicorn
+"""
+
+rst_epilog = """
+.. _Foreign Data Wrapper: http://www.postgresql.org/docs/current/static/ddl-foreign-data.html
+
+
+"""

doc/contribute.rst

@@ -5,8 +5,8 @@
 Send Us a Mail
 ==============
 
-Want to write kind words? You can send a mail on :mailaddress:`our Librelist
-mailing-list` and even take a look at :mailarchives:`the archives`.
+Want to write kind words? You can send a mail on .. meta: mailaddress_`our Librelist
+mailing-list` and even take a look at .. meta: mailarchives_`the archives`.
 
 
 Chat with Us on IRC
@@ -18,12 +18,15 @@ Want to say something? Join our IRC room: ##kozea on Freenode.
 Report Bugs
 ===========
 
-Found a bug? Want a new feature? Report a new issue on the :buglink:`Multicorn
+.. meta
+  :mailarchives:
+
+Found a bug? Want a new feature? Report a new issue on the :meta: buglink `Multicorn
 bug-tracker on GitHub`.
 
 
 Hack
 ====
 
-Interested in hacking? Feel free to clone the :codelink:`git repository on
+Interested in hacking? Feel free to clone the .. meta: codelink_`git repository on
 GitHub` if you want to add new features, fix bugs or update documentation.

doc/index.rst

@@ -3,21 +3,30 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Multicorn's documentation!
-=====================================
+
+Multicorn
+=========
+
+Multicorn is a PostgreSQL 9.1+ extension meant to make `Foreign Data Wrapper`_
+development easy, by allowing the programmer to use the Python programming
+language.
+
+If you just wanto use it as soon as possible, jump straight to the installation
+section.
+
 
 Contents:
 
 .. toctree::
   :maxdepth: 2
-  introduction.rst
+
   installation.rst
   getting-started.rst
+  introduction.rst
   foreign-data-wrappers.rst
   third-party-fdw.rst
   implementing-an-fdw.rst
   contribute.rst
-  index.rst
 
 Indices and tables
 ==================
@@ -26,3 +35,4 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+

doc/introduction.rst

@@ -5,13 +5,3 @@ Multicorn is a PostgreSQL 9.1+ extension meant to make `Foreign Data Wrapper`_
 development easy, by allowing the programmer to use the Python programming
 language.
 
-Ok, but why should I care ?
----------------------------
-
-- Multicorn allows you to access any data source in your PostgreSQL database.
-- You can leverage the full power of SQL to query your data sources
-- Every tool you use for SQL can be reused with those datasources (think about
-  an ORM, BI tool...)
-
-.. _Foreign Data Wrapper: http://people.planetpostgresql.org/andrew/uploads/fdw2.pdf
-

doc/multicorn_directives/__init__.py

@@ -0,0 +1,76 @@
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst import directives
+from docutils.nodes import Element
+from sphinx.builders.html import StandaloneHTMLBuilder
+
+
+
+class_map = {
+    'read': 'glyphicons-book-open',
+    'write': 'glyphicons-edit',
+    'transaction': 'glyphicons-database-plus',
+    'import_schema': 'glyphicons-disk-import'
+}
+
+class api_compat(Element):
+
+    def __init__(self, api=None):
+        self.api = api or {}
+        super(api_compat, self).__init__()
+
+def visit_api_compat_node_html(self, node):
+    self.body.append("<span>Supports: %s" % "".join(
+        ['<span class="%s" title="%s">%s</span>' %
+         (class_map.get(key), key, key)
+         for key in node.api]))
+
+
+def depart_api_compat_node_html(self, node):
+    self.body.append("</span>")
+
+
+def visit_api_compat_node_text(self, node):
+    self.add_text("Supported API: %s" % ",".join(node.api))
+
+
+def depart_api_compat_node_text(self, node):
+    pass
+
+
+def visit_api_compat_node_latex(self, node):
+    # TODO: make it render in latex
+    classes = node.get('classes', [])
+    self.body.append(r'\DUspan{%s}{' % ','.join(classes))
+
+
+def depart_api_compat_node_latex(self, node):
+    pass
+
+
+
+
+
+
+def setup(app):
+    app.add_directive('api_compat', APICompatDirective)
+    app.add_node(api_compat,
+                 html=(visit_api_compat_node_html, depart_api_compat_node_html),
+                 latex=(visit_api_compat_node_latex, depart_api_compat_node_latex),
+                 text=(visit_api_compat_node_text, depart_api_compat_node_text))
+
+
+class APICompatDirective(Directive):
+
+    has_content = True
+
+    option_spec = {
+        'read': directives.flag,
+        'write': directives.flag,
+        'transaction': directives.flag,
+        'import_schema': directives.flag
+    }
+
+    def run(self):
+        values = {key: key in self.options
+                  for key in self.option_spec}
+        return [api_compat(api=values)]

doc/third-party-fdw.rst

@@ -7,6 +7,12 @@ third-party modules available on the net:
     * rethinkdb-multicorn-postgresql-fdw
       A FDW for accessing RethinkDB databases
 
+      .. api_compat::
+         :read:
+         :write:
+         :transaction:
+         :import_schema:
+
       repository
           https://github.com/wilsonrmsorg/rethinkdb-multicorn-postgresql-fdw/