From 9bc43615e17dd008a179b3bbf36ccb3bb473bd8b Mon Sep 17 00:00:00 2001
From: Thomas Fillon <thomas@parisson.com>
Date: Fri, 25 Oct 2013 16:58:11 +0200
Subject: [PATCH] Fix doc in tutorial and enable testsetup and testcleanup to
 support transparent uses of external ressources in doctest

---
 doc/source/tutorial/AnalyzerResult.rst |  7 +--
 doc/source/tutorial/quick_start.rst    | 62 +++++++++++++++++++-------
 2 files changed, 51 insertions(+), 18 deletions(-)

diff --git a/doc/source/tutorial/AnalyzerResult.rst b/doc/source/tutorial/AnalyzerResult.rst
index e824c58..980c726 100644
--- a/doc/source/tutorial/AnalyzerResult.rst
+++ b/doc/source/tutorial/AnalyzerResult.rst
@@ -1,8 +1,9 @@
 .. This file is part of TimeSide
    @author: Thomas Fillon
 
-Analyzer Result examples
-=============================
+==========================
+ Analyzer Result examples
+==========================
 
 Example of use of the Aanalyzer Result structure
 
@@ -47,7 +48,7 @@ This default result has all the metadata and dataObject attribute
 
 
 Specification of time_mode
-=========================
+==========================
 Four different time_mode can be specified :
 
 - 'framewise' : Data are returned on a frame basis (i.e. with specified blocksize, stepsize and framerate)
diff --git a/doc/source/tutorial/quick_start.rst b/doc/source/tutorial/quick_start.rst
index def9c28..5b608e7 100644
--- a/doc/source/tutorial/quick_start.rst
+++ b/doc/source/tutorial/quick_start.rst
@@ -1,13 +1,39 @@
+=============
  Quick start
-============
+=============
 
 A most basic operation, transcoding, is easily performed with two processors:
 
- >>> import timeside
- >>> decoder = timeside.decoder.FileDecoder('sweep.wav')
- >>> encoder = timeside.encoder.VorbisEncoder("sweep.ogg")
+
+.. testsetup:: test_1,test_2,test_3
+
+   import timeside
+   import os
+   ModulePath =  os.path.dirname(os.path.realpath(timeside.analyzer.core.__file__))
+   wavFile = os.path.join(ModulePath , '../../tests/samples/sweep.wav')
+   decoder = timeside.decoder.FileDecoder(wavFile)
+
+.. testcleanup:: test_1
+
+   os.remove('sweep.ogg')
+
+.. testcleanup:: test_2
+
+   os.remove('graph.png')
+
+.. testcleanup:: test_3
+
+   os.remove('sweep.mp3')
+   os.remove('sweep.flac')
+
+.. doctest:: test_1
+
+ >>> import timeside # doctest: +SKIP
+ >>> decoder = timeside.decoder.FileDecoder('sweep.wav')# doctest: +SKIP
+ >>> encoder = timeside.encoder.VorbisEncoder('sweep.ogg')
  >>> pipe = decoder | encoder
  >>> pipe.run()
+ <timeside.core.ProcessPipe object at 0x...>
 
 As one can see in the above example, creating a processing pipe is performed with
 the binary OR operator.
@@ -15,19 +41,25 @@ the binary OR operator.
 Audio data visualisation can be performed using graphers, such as Waveform and
 Spectrogram. All graphers return an image:
 
- >>> import timeside
- >>> decoder = timeside.decoder.FileDecoder('sweep.wav')
- >>> spectrogram = timeside.grapher.Spectrogram(width=400, height=150)
- >>> (decoder | spectrogram).run()
- >>> spectrogram.render().save('graph.png')
+.. doctest:: test_2
+
+   >>> import timeside
+   >>> decoder = timeside.decoder.FileDecoder('sweep.wav') # doctest: +SKIP
+   >>> spectrogram = timeside.grapher.Spectrogram(width=400, height=150)
+   >>> (decoder | spectrogram).run()
+   <timeside.core.ProcessPipe object at 0x...>
+   >>> spectrogram.render().save('graph.png')
 
 It is possible to create longer pipes, as well as subpipes, here for both
 analysis and encoding:
 
- >>> import timeside
- >>> decoder = timeside.decoder.FileDecoder('sweep.wav')
- >>> levels = timeside.analyzer.Level()
- >>> encoders = timeside.encoder.Mp3Encoder('sweep.mp3') | timeside.encoder.FlacEncoder('sweep.flac')
- >>> (decoder | levels | encoders).run()
- >>> print levels.results
+.. doctest:: test_3
 
+   >>> import timeside
+   >>> decoder = timeside.decoder.FileDecoder('sweep.wav') # doctest: +SKIP
+   >>> levels = timeside.analyzer.Level()
+   >>> encoders = timeside.encoder.Mp3Encoder('sweep.mp3') | timeside.encoder.FlacEncoder('sweep.flac')
+   >>> (decoder | levels | encoders).run()
+   <timeside.core.ProcessPipe object at 0x...>
+   >>> print levels.results
+   {'level.max': GlobalValueResult(id_metadata=IdMetadata(id='level.max', name='Level Analyzer Max', unit='dBFS', description='', date='...', version='0.5.1', author='TimeSide'), data_object=DataObject(value=array([-6.021])), audio_metadata=AudioMetadata(uri='file://...sweep.wav', start=0.0, duration=8.0, is_segment=False, channels=None, channelsManagement=''), parameters={}), 'level.rms': GlobalValueResult(id_metadata=IdMetadata(id='level.rms', name='Level Analyzer RMS', unit='dBFS', description='', date='...', version='0.5.1', author='TimeSide'), data_object=DataObject(value=array([-9.856])), audio_metadata=AudioMetadata(uri='file://...sweep.wav', start=0.0, duration=8.0, is_segment=False, channels=None, channelsManagement=''), parameters={})}
-- 
2.39.5