Merge pull request #27 from bird-house/clean-up-docs

prepare release v0.6.0, clean up
bird-house · Sep 14, 2018 · a4c754e · a4c754e
2 parents 2be45b8 + 4bd72f1
commit a4c754e
Show file tree

Hide file tree

Showing 11 changed files with 74 additions and 77 deletions.
diff --git a/README.rst b/README.rst
@@ -1,5 +1,6 @@
-Birdhouse Docs
-==============
+=========
+Birdhouse
+=========
 
 .. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
    :target: http://birdhouse.readthedocs.io/en/latest/?badge=latest
@@ -17,8 +18,8 @@ Birdhouse Docs
    :target: https://gitter.im/bird-house/birdhouse?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
    :alt: Join the chat at https://gitter.im/bird-house/birdhouse
 
-
-Birdhouse Sphinx documentation and IPython Notebooks with examples.
+Birdhouse is a GitHub organization comprised of Python projects related
+to `Web Processing Services <http://geoprocessing.info/wpsdoc/>`_ to support climate data analysis.
 
 The full `documentation <http://birdhouse.readthedocs.io/en/latest/>`_
 is available on ReadTheDocs and in the `docs/` folder.
diff --git a/docs/source/admin_guide.rst b/docs/source/admin_guide.rst
@@ -8,7 +8,7 @@ Administrator Guidelines
     :depth: 2
 
 
-.. warning:: WARNING: This section is outdated ...
+.. warning:: This section is outdated ...
 
 .. _birdhouse_ecosystem:
 
@@ -17,15 +17,15 @@ Set up a birdhouse ecosystem server
 
 If you are already familiar with installing single standalone WPS (follow the :ref:`installation` guides in the documentations of e.g. emu), then you are ready to set up a birdhouse containing flyingpigeon (providing scientific analyses methods), malleefowl (to search and fetch data) and the pheonix (a graphic interface for a web browser including a WMS).
 
-general remarks:
-..................
+General Remarks
+...............
 
 | Check the :ref:`requirements` of your system!
 | The installation is done as **normal user**, root rights are causing conflicts.
 
 
-clone the repositories from gitHub:
-...................................
+Clone the Repositories from GitHub
+..................................
 
 It is recommended to collect the repositories in a seperate folder (e.g. birdhouse, but can have a name of your choice)::
 

diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -9,7 +9,7 @@ Architecture
     :depth: 2
 
 
-Framework overview
+Framework Overview
 ------------------
 
 .. image:: _images/framework.png
@@ -41,47 +41,42 @@ components to support them (the birds):
 
 .. _client_components:
 
-client side components
+Client Side Components
 ----------------------
 
 * `Phoenix`_: a web-based WPS client with ESGF data access
 * `Birdy`_: a WPS command line client and native library
 
-* `Phoenix web application <https://github.com/bird-house/pyramid-phoenix/issues>`_
-* `Birdy command line WPS client <https://github.com/bird-house/birdy/issues>`_
-
 .. _server_components:
-server side components
+
+Server Side Components
 ----------------------
 
+WPS services for climate data analysis:
+
 * `Flyingpigeon`_: services for the climate impact community
 * `Black Swan`_: services for the extreme weather event assessments
 * `Hummingbird`_: provides cdo and compliance-checker as a service
 * `Emu`_: some example WPS processes for demo
-* `Flyingpigeon WPS for climate impact <https://github.com/bird-house/flyingpigeon/issues>`_
-* `Hummingbird WPS processes for cdo and compliance checking <https://github.com/bird-house/hummingbird/issues>`_
-* `Emu WPS processes for demo and testing <https://github.com/bird-house/emu/issues>`_
-* `Malleefowl WPS base processes to access data <https://github.com/bird-house/malleefowl/issues>`_
 
+Many climate analysis operations are implemented using OpenClimateGIS_
+including the `python package icclim <http://icclim.readthedocs.io/en/latest/>`_.
 
-Many climate analysis operations are implemented using OpenClimateGIS_ including the `python package icclim <http://icclim.readthedocs.io/en/latest/>`_
+Supporting Services and libraries:
 
 * `Twitcher`_: an OWS Security Proxy
-* `Twitcher, an WPS security proxy <https://github.com/bird-house/twitcher/issues>`_
 * `Malleefowl`_: access to climate data (ESGF, ...) as a service
 * `Eggshell`_: provides common functionallity for Birdhouse WPS services
 
-
 You can find the source code of all birdhouse components on GitHub_.
 Docker images with birdhouse components are on `Docker Hub`_
 
-
 .. _filesandfolder:
 
 Files and Folders
 -----------------
 
-.. Warning: outdated
+.. warning:: This section is outdated. We are moving to a new deployment without Buildout.
 
 The birds have a similar folder structure. While library dependencies are stored within the conda deployment
 
@@ -104,7 +99,5 @@ Furthermore, in ``environment.yml``, the conda packages can be defined. It is re
 There are **log files** situated at:: ``~/birdhouse/var/log/pywps/``
 
 
-
-
 .. _GitHub: https://github.com/bird-house
 .. _`Docker Hub`: https://hub.docker.com/r/birdhouse
diff --git a/docs/source/communication.rst b/docs/source/communication.rst
@@ -55,9 +55,6 @@ The birdhouse wiki_ provides an area for supporting information that frequently
 changes and / or is outside the scope of the formal documentation.
 
 
-
-
-
 .. _`newsletter`: http://eepurl.com/dGbQ2X
 .. _`wiki`: https://github.com/bird-house/bird-house.github.io/wiki
 .. _`meetings`: https://github.com/bird-house/bird-house.github.io/wiki/Meetings

diff --git a/docs/source/dev_guide.rst b/docs/source/dev_guide.rst
@@ -8,6 +8,7 @@ Developer Guidelines
     :depth: 2
 
 .. _codeofconduct:
+
 Code of Conduct
 ---------------
 
@@ -104,15 +105,15 @@ Sublime
 Writing functions:
 ------------------
 
-.. todo: guidline for writing functions. Where to place, how to comment.
+.. todo:: Guideline for writing functions. Where to place, how to comment.
 
 .. _writing_WPS_process:
 
 Writing a WPS process
 ---------------------
 
 In birdhouse, we are using the PyWPS_ implementation of a :term:`Web Processing Service`.
-Please read the PyWPS `documentation <https://pywps.readthedocs.io/en/master/process.html>`_
+Please read the `PyWPS documentation <https://pywps.readthedocs.io/en/master/process.html>`_
 on how to implement a WPS process.
 
 .. note:: To get started quickly, you can try the Emu_ WPS with some example processes for PyWPS.
@@ -122,7 +123,7 @@ on how to implement a WPS process.
 Writing tests
 -------------
 
-.. todo: missing so far :-)
+.. todo:: Guideline to write tests. Look at the Emu_ to see examples.
 
 
 .. _writing_docs:
@@ -136,25 +137,26 @@ Last but not least, a very very important point is to write a good documentation
 * http://quick-sphinx-tutorial.readthedocs.io/en/latest/
 
 The documentation is automatically published to ReadTheDocs_ with GitHub webhooks.
-It is important to keep the :ref:`_codestyle` and write explanations to your functions. There is an auto-api for documentation of functions.
-.. todo: explanation of enabling spinx automatic api documentation.
+It is important to keep the :ref:`codestyle` and write explanations to your functions. There is an auto-api for documentation of functions.
+
+.. todo:: explanation of enabling spinx automatic api documentation.
 
 The main `documentation`_ (which you are reading now) is the starting point to
 get an overview of birdhouse. Each birdhouse component comes with
 its own Sphinx documentation and is referenced by the main birdhouse document.
 
-.. _conda:
 Environment with conda
 ----------------------
-.. todo: How to create a conda package
+
+.. todo:: How to create a conda package
 
 
 Make your own Bird
 ------------------
 
 If you are familiar with all the upper chapters you are ready to create your own WPS. The WPS in birdhouse are named after birds, so this section is giving you a guidline of how to make your own bird. Birds are sorted thematically, so before setting up a new one, make sure it is not already covered and just missing some processes and be clear in the new thematic you would like to provide.
 
- We have now a Cookiecutter_ template to create a new bird (PyWPS application).
+We have now a Cookiecutter_ template to create a new bird (PyWPS application).
 It is the recommended and fastest way to create your own bird:
 
 https://github.com/bird-house/cookiecutter-birdhouse

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,11 +1,4 @@
-.. Birdhouse documentation master file, created by
-   sphinx-quickstart on Tue Mar 10 15:22:06 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-*******
-Content
-*******
+.. include:: ../../README.rst
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -7,7 +7,7 @@ Installation Guidelines
     :local:
     :depth: 2
 
-.. warning:: WARNING: This section is outdated ...
+.. warning:: This section is outdated ...
 
 Birdhouse consists of several components like Malleefowl_ and Emu_. Each of them can be installed individually.
 The installation is done using the Python-based build system :term:`Buildout`.

diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -27,7 +27,7 @@ and maintain large storage infrastructures.
 .. _what_is_wps:
 
 What is WPS?
------------
+------------
 
 **Geographic Information Processing for the Web**
     *The Web Processing Service (WPS) offers a simple web-based method of finding, accessing, and using all kinds of calculations and models*.
@@ -49,7 +49,8 @@ compartments is a framework. WPS divides the operation into server and client si
 .. _wps_use_case:
 
 WPS Use Case
------------
+------------
+
 .. todo:: needs to be updated.
 
 A user runs WPS processes *remotely* on a machine with direct access to climate data archives.

diff --git a/docs/source/projects.rst b/docs/source/projects.rst
@@ -11,25 +11,28 @@ Projects using birdhouse
 
 Birdhouse is used in the following projects:
 
-.. todo: add some introduction sentences for each project
+.. todo:: add some introduction sentences for each project
+
+COPERNICUS
+----------
 
-COPERNICUS:
------------
 * CP4CDS: Climate Projects for the `Climate Data Store`_ (part of the European Union's `Copernicus Climate Change Service`_).
 
-OGC-Testbeds:
--------------
+OGC-Testbeds
+------------
+
+.. todo:: Add references to OGC testbed.
 
 * OGC Testbed 13: Enhancement of scheduling services
 * OGC Testbed 14: Enhancement of security
 
-PAVICS:
--------
+PAVICS
+------
 
 * PAVICS_: Platform for climate analysis and visualization by Ouranos_ and CRIM_, Canada.
 
-A2C2:
------
+A2C2
+----
 
 * A2C2_: Atmospheric flow Analogues for Climate Change
 

diff --git a/docs/source/publications.rst b/docs/source/publications.rst
@@ -57,7 +57,7 @@ Articles, book sections and conference proceedings and presentations related to
 
 * Gerics Hamburg User-Developer Workshop
 
-.. references:
+.. _references:
 
 References
 ----------

diff --git a/docs/source/release_notes.rst b/docs/source/release_notes.rst
@@ -9,15 +9,15 @@ Release Notes
    :depth: 2
    :backlinks: none
 
-Washington (December 2018)
-==========================
+Washington (December 2018, v0.6.1)
+==================================
 
 Birdhouse will be at the `AGU 2018 in Washington D.C. <https://fallmeeting.agu.org/2018/>`_.
 
-.. warning:: Comming next ...
+.. warning:: In the making ...
 
-Dar es Salaam (September 2018)
-==============================
+Dar es Salaam (September 2018, v0.6.0)
+======================================
 
 Birdhouse was present at the `FOSS4G 2018 in Dar es Salaam <https://2018.foss4g.org/>`_.
 
@@ -49,8 +49,8 @@ New Birds in the making:
 * Black Swan: https://github.com/bird-house/blackswan
 * Eggshell: https://github.com/bird-house/eggshell
 
-Montréal (March 2018)
-=====================
+Montréal (March 2018, v0.5.0)
+=============================
 
 We had a `workshop in Montréal <https://medium.com/birdhouse-newsletter/april-2018-74c8914648d9>`_ with CRIM and Ouranos.
 
@@ -81,8 +81,8 @@ New Birds in the making:
 * Cookiecutter: https://github.com/bird-house/cookiecutter-birdhouse
 
 
-Bonn (August 2016)
-==================
+Bonn (August 2016, v0.4.0)
+==========================
 
 Birdhouse was present at the `FOSS4G 2016 in Bonn <http://2016.foss4g.org/home.html>`_.
 
@@ -96,8 +96,8 @@ Highlighted Changes:
 * allow upload of files to processes.
 * updated Phoenix user interface.
 
-Paris (October 2015)
-====================
+Paris (October 2015, v0.3.0)
+============================
 
 * updated documents on readthedocs
 * OAuth2 used for login with GitHub, Ceda, ...
@@ -113,8 +113,8 @@ Paris (October 2015)
 * using birdy wps command line client
 
 
-Paris (September 2014)
-======================
+Paris (September 2014, v0.2.0)
+==============================
 
 * Phoenix UI as WPS client with ESGF faceted search component and a wizard to chain WPS processes
 * PyWPS based processing backend with supporting processes of Malleefowl
@@ -132,15 +132,22 @@ Paris (September 2014)
 * moved source code and documentation to birdhouse on GitHub
 
 
-Helsinki (May 2014)
-===================
+Helsinki (May 2014, v0.1.2)
+===========================
 
 * presentation of birdhouse at EGI, Helsinki
 * stabilized birdhouse and CSC processes
 * updated documenation and tutorials
 
-Vienna (April 2014)
-===================
+Vienna (April 2014, v0.1.1)
+===========================
+
+* presentation of birdhouse at EGU, Vienna.
+* "quality check" workflow for CORDEX data.
+
+Hamburg (December 2013, v0.1.0)
+===============================
+
+* First presentation of Birdhouse at GERICS_ (German Climate Service Center), Hamburg.
 
-* presentation of birdhouse at EGU, Vienna
-* "quality check" workflow for CORDEX data
+.. _GERICS: https://www.climate-service-center.de/