Initial docs setup

README.rst

@@ -1,53 +1,7 @@
 ==========================================================
-iati-docs-base: Template repo for IATI documentation sites
+Country Development Finance Data Docs
 ==========================================================
 
-Includes:
-
-* IATI documentation Sphinx theme
-* Scaffolding for translation
-* Instructions on how to create a new IATI documentation site
-* The "kitchen sink" comprehensive demonstration of Sphinx features rendered using the theme
-
-For more information on using the `IATI documentation site Sphinx theme <https://github.com/IATI/sphinx-theme>`_ , see `the theme documentation <https://iati-sphinx-theme.readthedocs-hosted.com/en/latest/>`_
-
-Creating a new IATI Documentation website
-=========================================
-
-Create the repo
----------------
-
-In order to create a new repo using this as a template, you need permission to create new repos in the IATI GitHub organisation. If you don't have this, talk to `an organisation owner <https://github.com/orgs/IATI/people>`_.
-
-If you have this permission, then click the "Use this template" button on the repo to create a new repo, using this as a template. 
-
-Configure the docs site
------------------------
-
-Go through docs/conf.py and replace all references to "IATI Validator" with the name of whatever you're documenting. 
-
-Set up ReadTheDocs
-------------------
-
-Then, set up the repo on ReadTheDocs by `logging in to app.readthedocs.com <https://app.readthedocs.com/dashboard/>`_ using GitHub. Permissions on ReadTheDocs are set via GitHub so you have to log in using GitHub, otherwise you won't be able to access anything.
-
-Once logged in, click Add Project and follow through the flow to add the project. If you get a banner saying "Failed to add deploy key to project Failed to add deploy key to GitHub project, ensure you have the correct permissions and try importing again.", you can ignore it(!) 
-
-Repeat the Add Project flow again for each language that you're adding translations for, using the same repo and following the convention of appending -fr/-es etc at the end of each project name, and setting the Language of the project to the appropriate value. 
-
-Then, go to the Settings of the English version of the docs, click "translations" in the menu, and add the extra projects you just created as Translations of the first. 
-
-Finally, go through each of the projects that you've just created, go to their Settings, and ensure that the Privacy Level is set to Public and that the "Build pull requests for this project" box is checked. 
-
-Write your content
-------------------
-
-You're now ready to write your content - see other documentation sites for examples of layouts and structure, and look at the "kitchen sink" for examples of Sphinx features. All content must be written in `ReStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ .
-
-See the "Contributing" section, below, for best practices on how to work on your content.
-
-Don't forget to remove the Kitchen Sink and these setup instructions before starting work on your own documentation. The content in the other sections below can stay as it's relevant to anyone wanting to work on the documentation in the future. 
-
 Building the Documentation
 ==========================
 

docs/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# IATI Validator documentation build configuration file,
+# IATI CDFD documentation build configuration file,
 # created by sphinx-quickstart on Wed Nov  2 14:17:45 2016.
 #
 # This file is execfile()d with the current directory set to its
@@ -143,8 +143,9 @@
 #
 html_theme_options = {
     "github_repository": "https://github.com/IATI/iati-docs-base",
-    "header_title_text": "IATI Docs Base",
-    "project_title": "IATI Docs Base",
+    "header_title_text": "Country Development Finance Data",
+    "project_title": "CDFD: Documentation",
+    "tool_nav_items": {"CDFD": "https://countrydata.iatistandard.org/"},
     "languages": ["en"],
 }
 
@@ -154,7 +155,7 @@
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = 'IATI Validator Docs'
+# html_title = 'IATI CDFD Docs'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -277,7 +278,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "sphinx.tex", "IATI Validator Docs", "IATI Secretariat", "manual"),
+    (master_doc, "sphinx.tex", "IATI CDFD Docs", "IATI Secretariat", "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -317,7 +318,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "sphinx", "IATI Validator Docs", [author], 1)]
+man_pages = [(master_doc, "sphinx", "IATI CDFD Docs", [author], 1)]
 
 # If true, show URL addresses after external links.
 #
@@ -333,7 +334,7 @@
     (
         master_doc,
         "sphinx",
-        "IATI Validator Docs",
+        "IATI CDFD Docs",
         author,
         "sphinx",
         "One line description of project.",

docs/data_fields.rst

@@ -0,0 +1,167 @@
+************************
+Data Fields
+************************
+
+This section provides a summary of all fields output by CDFD.
+To read more about the elements of the IATI Standard, visit the `IATI Standard website <https://iatistandard.org/en/iati-standard/203/>`_.
+
+|
+
+IATI Identifier	
+================
+The :iati-reference:`iati-identifier` is the unique identifier for an activity. 
+An activity in IATI is any individual piece of development or humanitarian work, the scope of which is defined by the organisation publishing the data. 
+
+Title
+========
+The :iati-reference:`title` of an activity.
+
+Reporting Organisation Group	
+============================
+The group of related organisations a :iati-reference:`reporting-org` belongs to, based on this `list <https://codelists.codeforiati.org/ReportingOrganisationGroup/>`_ developed by members of the IATI Community.
+
+Reporting Organisation
+========================
+The :iati-reference:`reporting-org` is the organisation that has published the activity. 
+Each organisation has a unique organisation identifier, shown in brackets in the CDFD output. 
+For example, UNICEF (XM-DAC-41122).
+
+Reporting Organisation Type	
+=============================	
+The type of organisation reporting an activity. 
+Values are defined in the `Organisation Type Codelist <https://iatistandard.org/en/iati-standard/203/codelists/organisationtype/>`_.
+
+Aid Type
+=========
+The type or modality of aid (e.g. general budget support, project-type interventions). 
+:iati-reference:`aid-type` is not available for all transactions/budgets as not all organisations have reported this information.
+Values are defined in the `OECD DAC codelist for Type of Aid <https://iatistandard.org/en/iati-standard/203/codelists/aidtype/>`_.
+
+Finance Type	
+==============
+The type of finance (e.g. loan, grant). 
+:iati-reference:`finance-type` is not available for all transactions/budgets as not all organisations have reported this information.
+Values are defined in the `OECD DAC codelist for Type of Finance <https://iatistandard.org/en/iati-standard/203/codelists/financetype/>`_.
+
+Flow Type	
+============
+The type of flow (e.g. official development assistance, other official flows, private flows). 
+:iati-reference:`flow-type` is not available for all transactions/budgets as not all organisations have reported this information.
+Values are defined in the `OECD DAC codelist for Type of Flow <https://iatistandard.org/en/iati-standard/203/codelists/flowtype/>`_.
+
+Provider Organisation	
+========================
+The :iati-reference:`provider-org` is the organisation from which the resources originated.
+
+Depending on the detail published, this field may include the name of the organsation, their unique organisation identifier, or both.
+The name used for the same organisation may vary between reporting organisations. 
+For example, AfDB, African Development Bank, African Development Bank Group, etc.
+
+Where organisations do not declare a :iati-reference:`provider-org` for a transaction, the logic described in the Methodology; :ref:`Provider and receiver organisations` section is followed.
+For budgets, the logic described in the Methodology; :ref:`Budget Handling` section is followed. 
+
+
+Provider Organisation Type	
+==========================
+The type of organisation(s) from which the resources originated.
+:iati-reference:`provider-org/@type` is not available for all transactions/budgets as not all organisations have reported this information.
+Values are defined in the `Organisation Type Codelist <https://iatistandard.org/en/iati-standard/203/codelists/organisationtype/>`_.
+
+Receiver Organisation	
+========================
+The organisation receiving the specified transaction amount. 
+Depending on the detail published, this field may include the name of the organsation, their unique organisation identifier, or both.
+
+Where organisations do not declare a :iati-reference:`receiver-org` for a transaction, the logic described in the Methodology; :ref:`Provider and receiver organisations` section is followed.
+For budgets, the logic described in the Methodology; :ref:`Budget Handling` section is followed. 
+
+Receiver Organisation Type
+===========================
+The type of organisation(s) receiving the specified transaction amount. 
+:iati-reference:`receiver-org/@type` is not available for all transactions/budgets as not all organisations have reported this information.
+Values are defined in the `Organisation Type Codelist <https://iatistandard.org/en/iati-standard/203/codelists/organisationtype/>`_.
+
+Transaction Type	
+========================
+The type of the transaction. 
+There are 13 transaction types that can be reported to IATI.
+Four are included in CDFD's dataset, plus budgets:
+
+* Incoming Funds
+* Outgoing Commitments
+* Disbursements 
+* Expenditure
+* Budget 
+
+Transaction types and their definitions are available in the `Transaction Type Codelist <https://iatistandard.org/en/iati-standard/203/codelists/transactiontype/>`_.
+
+Recipient Country or Region	
+===========================
+The country or region that was the recipient of this transaction. 
+:iati-reference:`recipient-country` values are defined in the `Country Codelist <https://iatistandard.org/en/iati-standard/203/codelists/country/>`_,
+and :iati-reference:`recipient-region` values are defined in the `Region Codelist <https://iatistandard.org/en/iati-standard/203/codelists/region/>`_.
+
+Multi Country	
+========================
+Indicates whether the activity has one or multiple recipient countries, where 1 = True and 0 = False.
+If it is a multi-country activity, this means that the estimated percentage to that country has been applied to the transaction / budget values.
+
+The logic of transaction splitting is described  in the Methodology; :ref:`Transaction Splitting` section. 
+
+Sector Category	
+================
+The category of the sector that an activity is supporting. 
+Sector category is not available for all transactions/budgets as not all organisations report sectors using the OECD DAC 5 digit codes, the first three numbers of which map to the sector categories.
+Values are defined in the `OECD DAC 3 Digit Sector codelist <https://iatistandard.org/en/iati-standard/203/codelists/sectorcategory/>`_.
+
+Sector
+========
+The sector that an activity is supporting. 
+:iati-reference:`sector` is not available for all transactions/budgets as not all organisations report sectors using the OECD DAC 5 digit codes.
+Values are defined in the `OECD DAC DAC 5 Digit Sector codelist <https://iatistandard.org/en/iati-standard/203/codelists/sector/>`_.
+
+Humanitarian	
+=============
+An indication of whether the transaction/budget can be categorized as humanitarian, where 1 = True and 0 = False.
+
+Calendar Year	
+==============
+The year in which the transaction occurred or the year for which the budget values have been aggregated.
+
+Calendar Quarter	
+=================
+This is the quarter in which the transaction occurred or the quarter for which the budget values have been aggregated.
+
+Quarters:
+
+* Q1: January - March
+* Q2: April - June
+* Q3: July - September
+* Q4: October - December
+
+Calendar Year and Quarter	
+==========================
+The year and quarter in which the transaction occurred or the year and quarter for which the budget values have been aggregated.
+
+URL	
+=====
+The link to the IATI activity page on d-portal.
+
+Value (USD)	
+============
+The value of the transaction/budget in U.S. Dollars.
+
+.. note::
+    Some organisations include negative transactions in their data. 
+
+    For disbursements, this typically means that money disbursed is being returned to the funder. 
+
+    For commitments, this may be an adjustment to an initial commitment.
+
+Value (EUR)	
+========================
+The value of the transaction/budget row in Euros.
+
+Value (Local currrency)
+========================
+The value of the transaction/budget row in the local currency, customised for each country. 

docs/example_queries.rst

@@ -0,0 +1,64 @@
+****************
+Example Queries
+****************
+
+1. :ref:`How do I find organisations involved in humanitarian responses? <q1>`
+2. :ref:`What external resources were spent in 2021 Q4 in Zimbabwe? <q2>`
+
+| 
+
+---------
+
+| 
+
+.. _q1: 
+1: How do I find organisations involved in humanitarian responses?
+-------------------------------------------------------------------
+
+A Local NGO is looking to coordinate with other organisations. They want to find a list of organisations who are supporting the humanitarian response in Lebanon.
+
+Using CDFD, they access the recipient country/region `Summary Dashboard for Lebanon <https://countrydata.iatistandard.org/data/recipient-country-or-region/LB/?filters=transaction_type%3A3,4,budget%3Byear%3A2024>`_. 
+The Dashboard includes an overview of budgets and spend by :iati-reference:`reporting-org`. These are the different organisations that have published IATI data.
+
+.. figure:: images/q1.svg
+    :width: 100 %
+    :align: center
+    :alt: Screenshot of the reporting organisation graph for Lebanon
+
+    CDFD Lebanon Dashboard: Explore the data by Reporting Organisation
+
+Using the “Customise” button allows them to create a custom data download from the reporting organisation graph. 
+
+They select the following options:
+
+* View the Dashboard as a table
+* Add :iati-reference:`provider-org` and :iati-reference:`receiver-org` using the columns drop down menu. These are the organisations listed as providing or receiving funding as part of the activity.
+* Add a humanitarian filter using the “More Filters” menu
+
+The `resulting table <https://countrydata.iatistandard.org/data/custom/?drilldowns=reporting_organisation_type%3Bprovider_organisation%3Breceiver_organisation&filters=humanitarian%3A1%3Brecipient_country_or_region%3ALB%3Btransaction_type%3A3,4,budget%3Byear%3A2024&displayAs=table>`_ can be downloaded in XLSX format for further analysis.
+
+.. note::
+    If :iati-reference:`provider-org` or :iati-reference:`receiver-org` are not specified for individual transactions, 
+    CDFD will populate these fields using the reporting and participating organisations elements. 
+    See the Methodology section on :ref:`Provider and receiver organisations` for more information.
+
+| 
+
+.. _q2: 
+2: What external resources were spent in 2021 Q4 in Zimbabwe?
+-------------------------------------------------------------------
+
+The Ministry of Finance in Zimbabwe needs data on external inflows to the country to feed into the quarterly calculation of Balance of Payments. 
+They want to find out about external resources spent in 2021 Q4 in Zimbabwe.
+
+Using CDFD, they access the recipient country/region `Summary Dashboard for Zimbabwe <https://countrydata.iatistandard.org/data/recipient-country-or-region/ZW/?filters=calendar_year_and_quarter%3A2021%20Q4%3Btransaction_type%3A3,4>`_, 
+and filter to the 2021 Q4 period. They also select the “Spending” resource flows option to focus on disbursements and expenditures. 
+
+.. figure:: images/q2.svg
+    :width: 100 %
+    :align: center
+    :alt: Screenshot of the CDFD Dashboard filter menu for Zimbabwe
+
+    CDFD Zimbabwe Dashboard: Filters
+
+They can then download tables of spend disaggregated by sector or reporting organisation, or customise the output further as needed. 

docs/faq.rst

@@ -0,0 +1,44 @@
+################################
+Frequently Asked Questions
+################################
+
+1. :ref:`What data is included in CDFD? <faq_1>`
+2. :ref:`When is CDFD updated? <faq_2>`
+3. :ref:`Why is there missing data? <faq_3>`
+4. :ref:`Where can I access bulk downloads? <faq_4>` 
+
+| 
+
+---------
+
+| 
+
+.. _faq_1: 
+
+\1. What data is included in CDFD?
+    Data published to the `International Aid Transparency Initiative <https://iatistandard.org/en/>`_ (IATI). These data come from the `IATI Registry <https://www.iatiregistry.org/>`_.
+
+.. _faq_2: 
+
+\2. When is CDFD updated?
+    CDFD is refreshed once per day.
+
+.. _faq_3:
+
+\3. Why is there missing data?
+    Data gaps likely indicate that an organisation has not included this information in their data. 
+    This may be due to differing levels of detail, or due to different update schedules.
+    In the outputs, any data gaps appear as 'No data' in the cells.
+
+.. _faq_4:
+
+\4. Where can I access bulk downloads?
+    We are currently working to improve access to bulk downloads of CDFD's outputs from the web interface. 
+    While this work is ongoing, bulk downloads can be found at the following links:
+
+    * `EN_CDFD.zip <https://cdfd.iati.opendataservices.coop/output/web/xlsx/cdfd-xlsx-files-en.zip>`_
+    * `FR_CDFD.zip <https://cdfd.iati.opendataservices.coop/output/web/xlsx/cdfd-xlsx-files-fr.zip>`_
+    * `ES_CDFD.zip <https://cdfd.iati.opendataservices.coop/output/web/xlsx/cdfd-xlsx-files-es.zip>`_
+    * `PT_CDFD.zip <https://cdfd.iati.opendataservices.coop/output/web/xlsx/cdfd-xlsx-files-pt.zip>`_
+
+    Note that this is a prototype service. There may be a delay of ~24-36 hours before recently published data is incorporated into these aggregate results.