Skip to content

Commit cb443ef

Browse files
hgreccohgrecco
committed
Extensive work on the documentation
1 parent ff11055 commit cb443ef

25 files changed

+1028
-552
lines changed

‎docs/_static/blocks/loop.png

22.3 KB
Loading

‎docs/_static/blocks/scan.png

23.2 KB
Loading

‎docs/_static/blocks/scanfeat.png

24.8 KB
Loading

‎docs/_static/guides/scanfrequency.png

41 KB
Loading

‎docs/_static/tutorial/scanfrequency.ui ‎docs/_static/guides/scanfrequency.ui

File renamed without changes.

‎docs/_static/tutorial/fungen.ui

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<ui version="4.0">
3+
<class>MainWindow</class>
4+
<widget class="QMainWindow" name="MainWindow">
5+
<property name="geometry">
6+
<rect>
7+
<x>0</x>
8+
<y>0</y>
9+
<width>328</width>
10+
<height>231</height>
11+
</rect>
12+
</property>
13+
<property name="windowTitle">
14+
<string>Function Generator</string>
15+
</property>
16+
<widget class="QWidget" name="centralwidget">
17+
<layout class="QVBoxLayout" name="verticalLayout">
18+
<item>
19+
<widget class="QGroupBox" name="configBox">
20+
<property name="title">
21+
<string>Configuration</string>
22+
</property>
23+
<layout class="QVBoxLayout" name="verticalLayout_3">
24+
<item>
25+
<layout class="QFormLayout" name="formLayout">
26+
<property name="fieldGrowthPolicy">
27+
<enum>QFormLayout::FieldsStayAtSizeHint</enum>
28+
</property>
29+
<item row="0" column="0">
30+
<widget class="QLabel" name="amplitudeLabel">
31+
<property name="text">
32+
<string>Amplitude</string>
33+
</property>
34+
</widget>
35+
</item>
36+
<item row="0" column="1">
37+
<widget class="QDoubleSpinBox" name="amplitude"/>
38+
</item>
39+
<item row="1" column="0">
40+
<widget class="QLabel" name="offsetLabel">
41+
<property name="text">
42+
<string>Offset</string>
43+
</property>
44+
</widget>
45+
</item>
46+
<item row="1" column="1">
47+
<widget class="QDoubleSpinBox" name="offset"/>
48+
</item>
49+
<item row="2" column="0">
50+
<widget class="QLabel" name="waveformLabel">
51+
<property name="text">
52+
<string>Waveform</string>
53+
</property>
54+
</widget>
55+
</item>
56+
<item row="2" column="1">
57+
<widget class="QComboBox" name="waveform"/>
58+
</item>
59+
<item row="3" column="0">
60+
<widget class="QLabel" name="frequencyLabel">
61+
<property name="text">
62+
<string>Frequency</string>
63+
</property>
64+
</widget>
65+
</item>
66+
<item row="3" column="1">
67+
<widget class="QDoubleSpinBox" name="frequency"/>
68+
</item>
69+
</layout>
70+
</item>
71+
</layout>
72+
</widget>
73+
</item>
74+
</layout>
75+
</widget>
76+
<widget class="QMenuBar" name="menubar">
77+
<property name="geometry">
78+
<rect>
79+
<x>0</x>
80+
<y>0</y>
81+
<width>328</width>
82+
<height>22</height>
83+
</rect>
84+
</property>
85+
</widget>
86+
<widget class="QStatusBar" name="statusbar"/>
87+
</widget>
88+
<resources/>
89+
<connections/>
90+
</ui>

‎docs/_static/tutorial/gui-app.png

-17.6 KB
Loading

‎docs/_static/tutorial/rich-gui-app.png

47.3 KB
Loading

‎docs/agreement.rst

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
.. _agreement:
22

3+
4+
Agreeement
5+
----------
6+
37
.. raw:: html
48

59
<iframe src="https://docs.google.com/spreadsheet/embeddedform?formkey=dEs1Qmk5bU1ua1dPcS1kX1A1bmtjS1E6MQ" width="760" height="816" frameborder="0" marginheight="0" marginwidth="0">Loading...</iframe>

‎docs/conf.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -132,8 +132,8 @@ def __getattr__(cls, name):
132132
sys.exit(1)
133133
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
134134

135-
#import driversdoc
136-
#driversdoc.main()
135+
import driversdoc
136+
driversdoc.main()
137137

138138
# Theme options are theme-specific and customize the look and feel of a theme
139139
# further. For a list of options available for each theme, see the

‎docs/guides/backend.rst

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
2+
3+
Refactoring for reusability
4+
---------------------------
5+
6+
Finally we will add a couple of lines to allow the user to define the host
7+
and port number of the TCP function generator. We will also refactor the
8+
code to extract the function that perform the actual frequency scan apart::
9+
10+
import time
11+
12+
def scan_frequency(inst, start, stop, step, wait):
13+
"""Scan frequency in an instrument.
14+
15+
:param start: Start frequency.
16+
:type start: Quantity
17+
:param stop: Stop frequency.
18+
:type stop: Quantity
19+
:param step: Step frequency.
20+
:type step: Quantity
21+
:param wait: Waiting time.
22+
:type wait: Quantity
23+
24+
"""
25+
in_secs = wait.to('seconds').magnitude
26+
current = start
27+
while current < stop:
28+
inst.frequency = current
29+
time.sleep(in_secs)
30+
current += step
31+
32+
33+
if __name__ == '__main__':
34+
import argparse
35+
36+
from lantz import Q_
37+
38+
from mydriver import LantzSignalGeneratorTCP
39+
40+
parser = argparse.ArgumentParser()
41+
42+
# Configure
43+
parser.add_argument('-H', '--host', type=str, default='localhost',
44+
help='TCP hostname')
45+
parser.add_argument('-p', '--port', type=int, default=5678,
46+
help='TCP port')
47+
48+
parser.add_argument('start', type=float,
49+
help='Start frequency [Hz]')
50+
parser.add_argument('stop', type=float,
51+
help='Stop frequency [Hz]')
52+
parser.add_argument('step', type=float,
53+
help='Step frequency [Hz]')
54+
parser.add_argument('wait', type=float,
55+
help='Waiting time at each step [s]')
56+
57+
args = parser.parse_args()
58+
59+
Hz = Q_(1, 'Hz')
60+
sec = Q_(1, 'sec')
61+
62+
def print_change(new, old):
63+
print('Changed from {} to {}'.format(old, new))
64+
65+
with LantzSignalGeneratorTCP(args.host, args.port) as inst:
66+
print(inst.idn)
67+
68+
inst.frequency_changed.connect(print_change)
69+
70+
scan_frequency(inst, args.start * Hz, args.stop * Hz,
71+
args.step * Hz, args.wait * sec)
72+
73+
74+
The first change you will notice is that we have now used a Quantity for the
75+
time. It might be meaningless as the script ask for the waiting time in
76+
seconds and the function used to wait (`time.sleep`) expects the time in
77+
seconds. But using a Quantity allows the caller of the function how the
78+
waiting is implemented.
79+
80+
Also notice that we have removed the print statement from inside the function
81+
to be able to reuse it in other applications. For example, we might want to use
82+
it in a silent command line application or in a GUI application.
83+
To know that the frequency has changed we have connected a reporting function
84+
(`print_change`) to a signal (`frequency_changed`). Lantz will call the
85+
function every time that the frequency changes. Every Feat has an associated
86+
signal that can be accessed by appending `_changed` to the name.

‎docs/guides/defaults.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. _defaults_dictionary:
2+
3+
=======================
4+
The DEFAULTS dictionary
5+
=======================

‎docs/guides/ui-driver.rst

+21-8
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,24 @@ While the test widget is very convenient is not good enough for visually attract
1212

1313
You can set the frequency and amplitude using sliders. The sliders are named `frequency` and `amplitude`.
1414

15+
For *educational* purposes, we show you three ways to do this. You will certainly use only the last and shortest way but showing you how it is done allows you to understand what is going on.
16+
1517

1618
The long way
1719
------------
1820

19-
You can connect each relevant driver Feat to the corresponding widget::
21+
You can connect each relevant driver Feat to the corresponding widget:
22+
23+
.. code-block:: python
2024
2125
import sys
2226
2327
# Import Qt related from lantz so it worsk with PyQt4 or PySide ...
2428
from lantz.utils.qt import QtGui
2529
30+
# From lantz we import the driver ...
31+
from lantz.drivers.examples.fungen import LantzSignalGenerator
32+
2633
# and a function named connect_feat that does the work.
2734
from lantz.ui.widgets import connect_feat
2835
@@ -35,7 +42,7 @@ You can connect each relevant driver Feat to the corresponding widget::
3542
frequency_widget = main.findChild((QtGui.QWidget, ), 'frequency')
3643
amplitude_widget = main.findChild((QtGui.QWidget, ), 'amplitude')
3744
38-
with LantzSignalGeneratorTCP('localhost', 5678) as inst:
45+
with LantzSignalGenerator('TCPIP::localhost::5678::SOCKET') as inst:
3946
4047
# We connect each widget to each feature
4148
# The syntax arguments are widget, target (driver), Feat name
@@ -60,15 +67,17 @@ and that is all. Under the hood `connect_feat` is:
6067
The short way
6168
-------------
6269

63-
If you have named the widgets according to the Feat name as we have done, you can save some typing (not so much here but a lot in big interfaces)::
70+
If you have named the widgets according to the Feat name as we have done, you can save some typing (not so much here but a lot in big interfaces):
71+
72+
.. code-block:: python
6473
6574
import sys
6675
6776
# Import Qt related from lantz so it worsk with PyQt4 or PySide ...
6877
from lantz.utils.qt import QtGui
6978
7079
# From lantz we import the driver ...
71-
from lantz.drivers.examples.fungen import LantzSignalGeneratorTCP
80+
from lantz.drivers.examples.fungen import LantzSignalGenerator
7281
7382
# and a function named connect_driver that does the work.
7483
from lantz.ui.widgets import connect_driver
@@ -78,7 +87,7 @@ If you have named the widgets according to the Feat name as we have done, you ca
7887
# We load the UI from the QtDesigner file. You can also use pyuic4 to generate a class.
7988
main = QtGui.loadUi('connect_test.ui')
8089
81-
with LantzSignalGeneratorTCP('localhost', 5678) as inst:
90+
with LantzSignalGenerator('TCPIP::localhost::5678::SOCKET') as inst:
8291
8392
# We connect the parent widget (main) to the instrument.
8493
connect_driver(main, inst)
@@ -92,14 +101,18 @@ Notice that now we do not need a reference to the widgets (only to the parent wi
92101
The shortest way
93102
----------------
94103

95-
As this is a commont pattern, we have a useful function for that::
104+
As this is a commont pattern, we have a useful function for that:
105+
106+
.. code-block:: python
96107
97108
import sys
98109
99-
# Import Qt related from lantz so it worsk with PyQt4 or PySide ...
110+
# From lantz we import the driver ...
111+
from lantz.drivers.examples.fungen import LantzSignalGenerator
112+
100113
from lantz.ui.app import start_gui
101114
102-
with LantzSignalGeneratorTCP('localhost', 5678) as inst:
115+
with LantzSignalGenerator('TCPIP::localhost::5678::SOCKET') as inst:
103116
start_gui('connect_test.ui', inst, sys.argv)
104117
105118

‎docs/guides/ui-feat-two-widgets.rst

+2
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ In many cases you want to have multiple widgets (e.g. different kind) connected
1111

1212
You can set the frequency using the slider or the double spin box. The slider is named `frequency__slider` and the spin is named `frequency`.
1313

14+
For *educational* purposes, we show you three ways to do this. You will certainly use only the last and shortest way but showing you how it is done allows you to understand what is going on.
15+
1416

1517
The long way
1618
------------

0 commit comments

Comments
 (0)