Doc aggregation (#42)

* architectue to framework

* test with fetch extern files

* include pelican

docs/source/conf.py

@@ -44,6 +44,8 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+intersphinx_mapping = {'pavics': ('https://raw.githubusercontent.com/Ouranosinc/pavics-sdi/master/docs/source/', None)}
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -316,6 +318,7 @@
                        'flyingpigeon': ('https://flyingpigeon.readthedocs.io/en/latest/', None),
                        'hummingbird': ('https://birdhouse-hummingbird.readthedocs.io/en/latest/', None),
                        'emu': ('https://emu.readthedocs.io/en/latest/', None),
+                       'pelican': ('https://github.com/bird-house/pelican', None),
                        'birdy': ('https://birdy.readthedocs.io/en/latest/', None),
                        'bootstrap': ('https://birdhousebuilderbootstrap.readthedocs.io/en/latest/', None),
                         }
@@ -338,6 +341,7 @@
 .. _Twitcher: http://twitcher.readthedocs.io/en/latest/
 .. _Flyingpigeon: http://flyingpigeon.readthedocs.io/en/latest/
 .. _Hummingbird: http://birdhouse-hummingbird.readthedocs.io/en/latest/
+.. _Pelican: https://github.com/bird-house/pelican
 .. _Emu: http://emu.readthedocs.io/en/latest/
 .. _Black Swan: https://github.com/bird-house/blackswan
 .. _Finch: https://github.com/bird-house/finch

docs/source/architecture.rst → docs/source/framework.rst

@@ -1,42 +1,39 @@
-.. _birdhouse_overview:
+.. _framework:
 
-
-Architecture
-============
+*******************
+birdhouse framework
+*******************
 
 .. contents::
     :local:
     :depth: 2
 
 
-Framework Overview
-------------------
+Birdhouse is organized in separate stand-alone software components. The stand-alone components are named after birds, which gives the entire project its name birdhouse. Due to the nature of Web processing services the components can be categorized into :ref:`client_components` as tools for the user and :ref:`server_components` to build the architecture of server side back-ends.
 
-.. image:: _images/framework.png
 
-ESGF_ is currently the main climate data resource (but more resources are possible).
-ESGF Solr-index is used to find ESGF data.
-The ESGF identity provider with OpenIDs and X509 certificate is used for authentication.
+.. _framework_structure:
+
+Framework structure
+-------------------
 
 There are several WPS services. Malleefowl_ is the main one for the Phoenix_ client.
 Malleefowl is used to search, download (with caching) ESGF data and to retrieve certificates.
 Malleefowl has also a workflow engine (dispel4py_) to chain WPS processes.
 
 The results of the WPS processes are stored on the file system and are accessible via URL (with a token id).
-
 Results can be shown on a Map using a Web Mapping Service (ncWMS, adagucserver).
-
 The PyCSW Catalog Service is used to register WPS services and also to publish WPS outputs.
 Published results in the PyCSW can also used as input source for processes again.
 
-WPS serivces can be accessed through web-applications like Phoenix or from scripts.
+ESGF_ is currently the main climate data resource (but more resources are possible).
+ESGF Solr-index is used to find ESGF data. The ESGF identity provider with OpenIDs and X509 certificate is used for authentication.
 
-.. note:: See also the `Birdhouse Presentation`_.
+WPS serivces can be accessed through web-applications like Phoenix or from scripts.
 
-.. _Birdhouse Presentation: https://github.com/bird-house/birdhouse-presentation
+.. image:: _images/framework.png
 
-Birdhouse is the home of Web Processing Services used in climate science and
-components to support them (the birds):
+.. note:: See also the :ref:`Publications and Presentations <publications>` for more information and details.
 
 
 .. _client_components:
@@ -59,6 +56,7 @@ WPS services for climate data analysis:
 * `Black Swan`_: services for the extreme weather event assessments
 * Hummingbird_: provides cdo and compliance-checker as a service
 * Finch_: services for climate indices calculation
+* Pelican_: Supporting ESGF compute API
 * Kingfisher_: Services for Earth-Observation data analysis
 
 Many climate analysis operations are implemented using OpenClimateGIS_
@@ -74,11 +72,9 @@ You can find the source code of all birdhouse components on GitHub_.
 Docker images with birdhouse components are on `Docker Hub`_
 
 Files and Folders
-.................
-
-.. _note: See also administrator guidelines
+-----------------
 
-This is an overview of folder structure and important files for administration of a server-side birdhouse ecosystem.
+This is an overview of folder structure and important files for :ref:`administration of a server-side <admin_guide>` birdhouse ecosystem.
 
 It is recommended to clone the separated WPS services (birds) into one top level folder like:
 
@@ -125,8 +121,5 @@ are situated in:
   $ ./{birdname}/tests
   $ ./{birdname}/tests/testdata
 
-.. _note:: See also the administration guideline to set up a birdhouse ecosystem.
-.. _todo:: add locations of mongodb celery etc...
-
 .. _GitHub: https://github.com/bird-house
 .. _`Docker Hub`: https://hub.docker.com/r/birdhouse

docs/source/index.rst

@@ -4,11 +4,11 @@
    :maxdepth: 2
 
    overview
-   architecture
+   framework
+   projects
    guidelines
    ideas/index
    communication
-   projects
    publications
    release_notes
    license

docs/source/overview.rst

@@ -11,15 +11,15 @@ Overview
 
 .. _introduction:
 
+Birdhouse is a collaborative project open for the community to participate. It is a software framework containing a collection of `Web Processing Service`_ (WPS). The deployed algorithms are focusing on Earth Systems and environmental data processing with the philosophy of streamlining the software development and deployment. By supporting climate, earth observation and biodiversity data and processes, Birdhouse can be used in a wide array of Earth sciences projects and workflows. The core benefit of this project is to allow the seamless use of climate services developed by a diverse network of national meteorological offices, regional climate service providers, academics, not-for-profit research centers and private industry. As governments move toward open-data policies, there will be a need for analytical services that extract value out of the deluge of information. Using an interoperable software architecture, institutions can provide both data and services allowing users to process the data remotely from a laptop, instead of having to acquire and maintain large storage infrastructures.
 
-Introduction
-------------
 
-Birdhouse is a collaborative project open for the community to participate. It is a software framework containing a collection of `Web Processing Service`_ (WPS). The deployed algorithms are focusing on Earth Systems and environmental data processing with the
-philosophy of streamlining the software development and deployment. By supporting climate, earth observation and biodiversity data and processes, Birdhouse can be used in a wide array of Earth sciences projects and workflows. The core benefit of this project is to
-allow the seamless use of climate services developed by a diverse network of national meteorological offices, regional climate service providers, academics, not-for-profit research centers and private industry. As governments move toward open-data policies, there will be a need for analytical services that extract value out of the deluge of information. Using an interoperable software architecture, institutions can provide both data and services allowing users to process the data remotely from a laptop, instead of having to acquire and maintain large storage infrastructures.
+.. _documentation_structure
+
+Documentation structure
+-----------------------
 
-The documentation of birdhouse is representing its nature of separate software components and therefor organized in separate documentations. Birdhouse is being used by international working groups pitching up projects with individual focus on the projects objectives. The following graph shows an overview of the documentations organization and how they are aggregated to each other for a better understanding of where to find which information:
+The documentation of birdhouse is representing its nature of separate software components and therefor organized in separate documentations according to the :ref:`birdhouse framework structure <framework_structure>`. Birdhouse is being used by international working groups pitching up projects with individual focus on the projects objectives. The following graph shows an overview of the documentations organization and how they are aggregated to each other for a better understanding of where to find which information:
 
 
 .. image:: _images/Documentation_aggrgation.png

docs/source/projects.rst

@@ -1,17 +1,25 @@
 
 .. _projects:
 
-Projects using birdhouse
-========================
+Architectures examples
+======================
 
 
 .. contents::
     :local:
     :depth: 3
 
-Birdhouse is used in the following projects:
+The birdhouse :ref:`framework is modular organized <framework_structure>` to enable a flexible architecture design depending on the projects needs. Due to the OCG Standard, software components non-birdhouse components can be combined for interoperability. Here are some examples of real projects to show the flexibility and potential of the birdhouse framework.
+
+PAVICS
+------
+
+* PAVICS_: Platform for climate analysis and visualization by Ouranos_ and CRIM_, Canada.
+* PAVICS-Hydro_ : Additional services for PAVICS_ allowing users to perform hydrological modeling and analysis.
+
+.. literalinclude:: https://ouranosinc.github.io/pavics-sdi/_sources/arch/backend.rst.txt
+   :language: txt
 
-.. todo:: add some introduction sentences for each project
 
 COPERNICUS
 ----------
@@ -26,15 +34,6 @@ OGC-Testbeds
 * OGC Testbed 13: Enhancement of scheduling services
 * OGC Testbed 14: Enhancement of security
 
-PAVICS
-------
-
-* PAVICS_: Platform for climate analysis and visualization by Ouranos_ and CRIM_, Canada.
-* PAVICS-Hydro_ : Additional services for PAVICS_ allowing users to perform hydrological modeling and analysis.
-
-.. literalinclude :: https://raw.githubusercontent.com/Ouranosinc/pavics-sdi/master/docs/source/index.rst
-   :language: rst
-
 
 A2C2
 ----