Documentation for writing impact functions #487

Open
uniomni opened this Issue Feb 1, 2013 · 5 comments

Projects

None yet

4 participants

@uniomni

To assist new developers in writing impact functions, it would help to have some templates e.g. for each combination of hazard and exposure data types.

@uniomni uniomni was assigned Feb 1, 2013
@uniomni

It was discussed and agree that we should rather produce some documentation guiding (power) users in writing new impact functions. Perhaps on for each relevant combination of impact layer types.

@uniomni uniomni added a commit that referenced this issue Feb 26, 2013
@uniomni uniomni First cut of impact function guide done (#487) - still need example w…
…ith assign_hazard_level_to_exposure.
78c8042
@uniomni

A first cut is available at http://inasafe.org/developer-docs/writing_impact_functions.html

Outstanding are

  • How to link from document to docstring in the source documentation
  • Writing a section showing the use of the function assign_hazard_values_to_exposure_data
  • Writing examples for other data types
@uniomni uniomni added a commit that referenced this issue Mar 4, 2013
@uniomni uniomni Wrote sections on deploying impact functions and also the use of assi…
…gn_hazard_values_to_exposure_data towards issues #487
627f0b0
@uniomni

Some of the cross references were broken due to a recent restructure of the docs. For example, the current references to ../static are no longer valid.
Need to be modified as per Tim's instructions:

* place your static files under resources//foo.resource
* don't use the .. in front of static paths anymore so e.g.

.. figure:: /static/plugin-manager.png
   :align: center

* when post-translate.sh script runs it does the following:
  - copies resources/en source/static
  - overcopies resources/ source/static

* In this way the en resources form a baseline and anything a translator might have prepared will mask out the en version of a resource, otherwise the original en version is show.
 
To generate docs do

make docs


@timlinux

Something to investigate image:: references are still using the ../ prefix and seem to work, but figures are not:

timlinux@waterfall:~/dev/python/inasafe-dev/docs/source$ egrep -r "image::"
user-docs/dock.rst:   .. image:: ../../toggle-traceback.png If you click on this button, it
user-docs/dock.rst.orig:   .. image:: ../../toggle-traceback.png If you click on this button, it
tutorial-docs/tutorial.rst.orig:.. image:: /static/tutorial/001.png
tutorial-docs/tutorial.rst.orig:.. image:: ../static/tutorial/001.png
tutorial-docs/tutorial.rst.orig:.. image:: /static/tutorial/002.png
etc.

developer-docs/platform_windows.rst:.. figure:: /static/msysgit-step1.jpg
developer-docs/platform_windows.rst:.. figure:: /static/msysgit-step2.jpg
developer-docs/platform_windows.rst:.. figure:: /static/msysgit-step3.jpg
developer-docs/platform_windows.rst:.. figure:: /static/msysgit-step4.jpg
etc

So I still need to get a proper handle on why ../ works in some cases and not in others. My understanding was/is that when you reference a resource, it uses a relative path to the source file so for this scenario:

source
-- user-docs
---- foo.rst
-- developer-docs
-- static
---- user-docs
------ foo.img

For referencing foo.img from foo.rst my understanding is the path should be: ../../static/user-docs/foo.img but I need to confirm this is actually the case...and how sphinx is interpretting absolute paths like /static/user-docs/foo.img.

Regards

Tim

@ismailsunni ismailsunni added a commit that referenced this issue Mar 19, 2013
@ismailsunni ismailsunni Add some detail for #487 989db2f
@assefay

In inasafe/inasafe-doc#116 changing to relative paths seem to work on local build. Is this the proper modification to do ?

@uniomni uniomni removed their assignment Nov 16, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment