Merge pull request #26 from OpenAgFunding/td-documentation

Td documentation

.gitignore

@@ -1,3 +1,5 @@
 .project
 .Rproj.user
 .ipynb_checkpoints
+.ve
+_build

.sublime-project

@@ -0,0 +1,7 @@
+{
+    "settings":
+    {
+        "spell_check": true,
+        "dictionary": "Packages/Language - English/en_US.dic"
+    }
+}

README.md

@@ -12,13 +12,52 @@ To do so, the project will identify current data needs and propose relevant chan
 
 For more information on the Initiative for Open Ag Funding, please contact [David Duffeck](dduffeck@interaction.org).
 
-
 ## This repository
 
 This repository is a workspace for development of approaches to address the current gap in data availability and usability.
 
 You can [engage in discussions through the issue tracker](https://github.com/OpenAgFunding/development/issues) and you will find a growing collection of documentation here as the project develops. 
 
+## Building the documentation
+
+The docs folder contains documentation on use of IATI for Agriculture. 
+
+The documentation is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) and built with [Sphinx](http://www.sphinx-doc.org/en/1.5.1/)
+
+To build the documentation locally:
+
+(1) Clone the project and setup a python virtual environment
+
+```
+git clone https://github.com/OpenAgFunding/development.git
+virtualenv .ve -p python3
+source .ve/bin/activate
+pip install -r docs/requirements.txt
+```
+
+(2) Enter the documentation folder and build the project
+
+```
+cd docs
+make dirhtml
+```
+
+(3) Serve the files using pythons local web server
+
+```
+cd _build/dirhtml
+python3 -m http.server
+```
+
+The documentation site will now be accessible at http://localhost:8000/
+
+On OSX you can use fswatch to rebuild whenever there are updates to the markdown files:
+
+```
+fswatch -o *.md |  xargs -n1 make dirhtml &
+```
+
+
 ## Partners
 
 The Initiative for Open Ag Funding is a partnership project, co-ordinated by [InterAction](http://www.interaction.org) and working with [Development Gateway](http://www.developmentgateway.org/), the [Foundation Center](http://foundationcenter.org/), [Publish What You Fund](http://www.publishwhatyoufund.org/), and the [CGIAR Research Program on Policies, Institutions and Markets (PIM)](http://www.pim.cgiar.org/).

docs/_exts/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinxcontrib
+    ~~~~~~~~~~~~~
+
+    This package is a namespace package that contains all extensions
+    distributed in the ``sphinx-contrib`` distribution.
+
+    :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+__import__('pkg_resources').declare_namespace(__name__)
+

docs/_exts/doctabs.py

@@ -0,0 +1,59 @@
+# Adapted from the doctabs directive
+
+# -*- coding: utf-8 -*-
+"""
+Examplecode specs
+=================
+"""
+import os
+from docutils.parsers.rst import Directive
+from docutils import nodes
+from sphinx.util.osutil import copyfile
+
+
+CSS_FILE = 'doctabs.css'
+JS_FILE = 'doctabs.js'
+
+
+class DocTabsDirective(Directive):
+    """
+    This directive is intended to be used to contain a group of 
+    blocks which are being used to show code examples in many different
+    languages. When rendered as HTML the the examples will all be rolled up
+    into a single display area with buttons to select between the different
+    languages.
+    """
+
+    has_content = True
+
+    def run(self):
+        self.assert_has_content()
+        text = '\n'.join(self.content)
+        node = nodes.container(text)
+        node['classes'].append('doc-tabs')
+        self.add_name(node)
+        self.state.nested_parse(self.content, self.content_offset, node)
+        return [node]
+
+
+def add_assets(app):
+    app.add_stylesheet(CSS_FILE)
+    app.add_javascript(JS_FILE)
+
+def copy_assets(app, exception):
+    if app.builder.name != 'html' or exception:
+        return
+    app.info('Copying doctabs stylesheet/javascript... ', nonl=True)
+    dest = os.path.join(app.builder.outdir, '_static', CSS_FILE)
+    source = os.path.join(os.path.abspath(os.path.dirname(__file__)), CSS_FILE)
+    copyfile(source, dest)
+    dest = os.path.join(app.builder.outdir, '_static', JS_FILE)
+    source = os.path.join(os.path.abspath(os.path.dirname(__file__)), JS_FILE)
+    copyfile(source, dest)
+    app.info('done')
+
+def setup(app):
+    app.add_directive('doc-tabs',  DocTabsDirective)
+    app.connect('builder-inited', add_assets)
+    app.connect('build-finished', copy_assets)
+

docs/_static/doctabs.css

@@ -0,0 +1,38 @@
+ul.example-selector {
+    display:block;
+    list-style-type: none;
+    height: 15px;
+    margin: 0;
+    padding: 0;
+}
+ul.example-selector li {
+    display: block;
+    cursor: pointer;
+    font-weight: bold;
+    margin: 0 5px 0 0;
+    padding: 2px 3px;
+    float: left;
+    background-color: #999;
+    color: #fff;
+    -moz-border-radius: 5px;
+    -webkit-border-radius: 5px;
+    border-radius: 5px;
+    -khtml-border-radius: 5px;
+}
+ul.example-selector li:hover {
+    background-color: #777;
+}
+ul.example-selector li.selected {
+    background-color: #555;
+}
+ul.example-selector li.selected:hover {
+    background-color: #333;
+}
+
+div.doc-tabs.container {
+    width:inherit;
+}
+
+div.csv.container {
+    width:inherit;
+}

docs/_static/doctabs.js

@@ -0,0 +1,55 @@
+/**
+ * Dynamic multiple language example code block.
+ * Adapted from examplecode to work with multiple separate blocks. 
+ */
+
+function e1() {
+  var u='',i=0;
+  while(i++<36) {
+    var c='xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'[i-1],r=Math.random()*16|0,v=c=='x'?r:(r&0x3|0x8);
+    u+=(c=='-'||c=='4')?c:v.toString(16)
+  }
+  return u;
+}
+
+$(function() {
+
+  $('div.doc-tabs').each(function() {
+    var example_sel = $('<ul />', { class: "example-selector" });
+    var i = 0;
+    $(this).children('div').each(function() {
+      tabid = e1()
+      firstClass = $(this).attr('class').split(' ')[0]
+      title = firstClass.replace("highlight-","").replace("admonition-","")
+
+      var sel_item = $('<li />', {
+          class: tabid,
+          text: title
+      });
+      if (i++) {
+        $(this).hide();
+      } else {
+        sel_item.addClass('selected');
+      }
+      example_sel.append(sel_item);
+      $(this).addClass(tabid);
+      $(this).addClass('example');
+    });
+    $(this).prepend(example_sel);
+    example_sel = null;
+    i = null;
+  });
+
+  $('div.doc-tabs ul.example-selector li').click(function(evt) {
+    evt.preventDefault();
+    $('ul.example-selector li').removeClass('selected');
+    var sel_class = $(this).attr('class');
+    $(this).parents("div.container").children("div.example").hide();
+    // $('div.example').hide();
+    $('div.' + sel_class).show();
+    $('ul.example-selector li.' + sel_class).addClass('selected');
+    sel_class = null;
+  });
+
+});
+

docs/about.md

@@ -1,4 +1,59 @@
 About
 =====
 
+```eval_rst
+.. image:: assets/IOAF_logo_color_RGB.jpg
+   :width: 300 px
+   :height: 133 px
+   :alt: Project Logo
+   :align: center
+```
 
+<p></p>
+
+The [Initiative for Open Ag Funding](https://www.interaction.org/project/open-ag-funding/overview) is working to make sure that development actors working in agriculture and food security have the data they need to make smarter investment decisions, and to ultimately end hunger and food insecurity.
+
+You can [read more about the Initiative here](https://www.interaction.org/project/open-ag-funding/overview).
+
+
+```eval_rst
+.. image:: assets/project-toc.png
+   :alt: Project theory of change
+   :align: center
+```
+
+## The Open Ag Funding data framework
+On this site you can find out **how to publish and use Open Ag Funding data** that is fit for purpose to support donor co-ordination and more effective use of resources for agricultural development and food security. 
+
+You can: 
+
+* Read more about [how we are building on the International Aid Transparency Initiative (IATI) data standard](iati.md);
+* Explore the [priority data elements needed for effective Open Ag Funding data](framework.md);
+* View the technical documentation on how to prepare your data in XML or spreadsheet formats; 
+* Read background research from the project
+
+## Share your data
+
+**Does your organization provides funding for agricultural development or food security?** If so -  we need your data. 
+
+* **If you already publish data using the IATI standard**, you can enhance your existing data to make it Open Ag ready. 
+
+
+* **If you do not currently publish structured data on your funding or investments**, you can [follow these simple steps to plan out new open data publication](getting_started.md).  
+
+
+* **Not sure why you would share your data?** Read more here about the benefits.
+
+Looking for support to publish? We're offering free publisher support during 2017. 
+
+## Explore Open Ag Funding Data
+
+Over 2017 we will be supporting the development of a range of tools that can  help you explore and analyze data published according to the Open Ag Funding framework. 
+
+Check back for details of tools here later in 2017, or [get in touch](contact.md) to let us know about the data analysis you want to be able to carry out, and we'll see if we can signpost you to existing resources. 
+
+## Interested in other datasets?
+
+The [International Aid Transparency Initiative](http://www.aidtransparency.net) brings together data from 100s or donors on funding for development. 
+
+The [Global Open Data for Agriculture and Nutrition](http://www.godan.info) network supports advocacy and action on open data across the agriculture sector. 

docs/benefits.md

@@ -0,0 +1,4 @@
+Benefits
+========
+
+> This page is to be updated with more on the case for Open Ag Funding data

docs/codelists.md

@@ -0,0 +1,19 @@
+Codelists
+=========
+
+The most widely used codelist for classifying aid activities and investments (the OECD DAC CRS Purpose codes) does not provide enough specificity when it comes to agriculture and food security. 
+
+As a result, the [Open Ag Funding framework](framework.md) asks funders to provide additional activity classification using a detailed agricultural vocabulary.
+
+> This page will be updated following the tool development workshop, and final confirmation of codelist to be used. 
+
+The two candidate classifications for this are:
+
+* GACS - the General Agricultural Concept Scheme;
+
+and 
+
+* AGROVOC - The Agricultural Vocabulary of the Food and Agriculture Organisation
+
+These are both ontologies, and cross-walks exist between them. This means that they contain structured terms, allowing funders to choose the level of detail to classify their activities to. 
+

docs/conf.py

@@ -22,7 +22,9 @@
 # sys.path.insert(0, os.path.abspath('.'))
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser
+import sys, os
 
+sys.path.append(os.path.abspath('_exts'))
 
 # -- General configuration ------------------------------------------------
 
@@ -36,6 +38,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'doctabs'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -341,6 +344,7 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
+intersphinx_mapping = {'iati': ('http://iatistandard.org/202/', None)}
 
 
 def setup(app):
@@ -350,3 +354,19 @@ def setup(app):
         'enable_eval_rst': True
         }, True)
     app.add_transform(AutoStructify)
+
+import guzzle_sphinx_theme
+
+# Adds an HTML table visitor to apply Bootstrap table classes
+html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator'
+html_theme_path = guzzle_sphinx_theme.html_theme_path()
+html_theme = 'guzzle_sphinx_theme'
+
+# Register the theme as an extension to generate a sitemap.xml
+extensions.append("guzzle_sphinx_theme")
+
+# Guzzle theme options (see theme.conf for more information)
+html_theme_options = {
+    # Set the name of the project to appear in the sidebar
+    "project_nav_name": "Open Ag Funding",
+}

docs/contact.md

@@ -0,0 +1,6 @@
+Contact
+=======
+
+If you want to know more about the Open Ag Funding project overall, please contact lead partner, Interaction, using the [contact details on the project website here](https://www.interaction.org/project/open-ag-funding/overview).
+
+For questions about the data quality framework, get in touch with [Steven Flower](mailto:steven.flower@opendataservices.coop)