Skip to content

Commit 492bcbe

Browse files
tomvanmeletomvanmele
committed
docstring updates, converting to numpy style
1 parent ede727c commit 492bcbe

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

91 files changed

+2338
-1606
lines changed

‎src/compas/com/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
88
.. module:: compas.com
99
10+
:mod:`compas.com` provides functionality for communicating with external software.
11+
1012
1113
Matlab
1214
======

‎src/compas/com/matlab_/client.py‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,6 @@
2323
class MatlabClient(object):
2424
"""Communicate with Matlab through Windows' COM interface.
2525
26-
Note
27-
----
28-
This implementation uses Windows' COM interface to communicate with Matlab.
29-
Therefore, it is obviously only available on Windows.
30-
When an instance of this class is created, it automatically connects to Matlab,
31-
and initializes a lease that keeps the interface alive for at least 5 minutes
32-
such that subsequent calls can be executed immediately.
33-
After every call, the lease is renewed...
34-
3526
Parameters
3627
----------
3728
verbose : bool
@@ -44,6 +35,15 @@ class MatlabClient(object):
4435
The name of the Matlab workspace.
4536
Default is ``'base'``.
4637
38+
Notes
39+
-----
40+
This implementation uses Windows' COM interface to communicate with Matlab.
41+
Therefore, it is obviously only available on Windows.
42+
When an instance of this class is created, it automatically connects to Matlab,
43+
and initializes a lease that keeps the interface alive for at least 5 minutes
44+
such that subsequent calls can be executed immediately.
45+
After every call, the lease is renewed...
46+
4747
Examples
4848
--------
4949
>>> matlab = MatlabClient(interactive=True)
@@ -61,9 +61,9 @@ class MatlabClient(object):
6161
6262
See Also
6363
--------
64-
* compas.com.mlab.MatlabEngine
65-
* compas.com.mlab.MatlabSession
66-
* compas.com.mlab.MatlabProcess
64+
compas.com.mlab.MatlabEngine
65+
compas.com.mlab.MatlabSession
66+
compas.com.mlab.MatlabProcess
6767
6868
"""
6969

‎src/compas/com/matlab_/engine.py‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,7 @@ def __init__(self, message=None):
2727

2828

2929
class MatlabEngine(object):
30-
"""Communicate with Matlab through the MATLAB engine [mathworks2017a]_, [mathworks2017b]_,
31-
[mathworks2017c]_, [mathworks2017d]_, [mathworks2017e]_.
30+
"""Communicate with Matlab through the MATLAB engine.
3231
3332
Attributes
3433
----------
@@ -38,6 +37,23 @@ class MatlabEngine(object):
3837
session_name : str
3938
The name of the current Matlab session.
4039
40+
Notes
41+
-----
42+
For more info, see [1]_, [2]_, [3]_, [4]_, [5]_.
43+
44+
References
45+
----------
46+
.. [1] MathWorks, 2017. *MATLAB APY for Python*.
47+
Available at: https://ch.mathworks.com/help/matlab/matlab-engine-for-python.html
48+
.. [2] MathWorks, 2017. *Pass Data to MATLAB from Python*.
49+
Available at: https://ch.mathworks.com/help/matlab/matlab_external/pass-data-to-matlab-from-python.
50+
.. [3] MathWorks, 2017. *Use MATLAB Arrays in Python*.
51+
Available at: https://ch.mathworks.com/help/matlab/matlab_external/use-matlab-arrays-in-python.html
52+
.. [4] MathWorks, 2017. *Use MATLAB Engine Workspace in Python*.
53+
Available at: https://ch.mathworks.com/help/matlab/matlab_external/use-the-matlab-engine-workspace-in-python.html
54+
.. [5] MathWorks, 2017. *Call MATLAB Functions from Python*.
55+
Available at: https://ch.mathworks.com/help/matlab/matlab_external/call-matlab-functions-from-python.html
56+
4157
Examples
4258
--------
4359
>>> matlab = MatlabEngine()

‎src/compas/com/matlab_/process.py‎

Lines changed: 31 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -35,35 +35,37 @@ def __init__(self, message=None):
3535
class MatlabProcess(object):
3636
"""Communicate with Matlab through a subprocess.
3737
38-
Parameters:
39-
matlab_exec (str, optional) : Path to the Matlab executable.
40-
Defaults to `matlab`.
41-
ws_data (dict, optional) : Workspace data to be loaded at startup.
42-
Defaults to an empty dict.
43-
ws_filename (str, optional) : Filename for workspace storage.
44-
Defaults to `'./workspace.mat'`.
45-
46-
Examples:
47-
>>> m = MatlabProcess()
48-
49-
>>> m.start()
50-
>>> m.write_value('a', 37)
51-
>>> m.run_command('tf = isprime(a);')
52-
>>> m.read_workspace()
53-
>>> m.stop()
54-
>>> print(m.ws_data)
55-
56-
>>> m.write_value('a', 17)
57-
>>> m.run_command('res = isprime(a);')
58-
>>> m.read_value('res')
59-
True
60-
61-
>>> m.run_command('res = isprime(a);', ivars={'a': 17})
62-
>>> m.read_value('res')
63-
True
64-
65-
>>> m.run_command('res = isprime(a);', ivars={'a': 17}, ovars={'res': None})
66-
{'res': True}
38+
Parameters
39+
----------
40+
matlab_exec : str, optional
41+
Path to the Matlab executable. Defaults to ``matlab``.
42+
ws_data : dict, optional
43+
Workspace data to be loaded at startup. Defaults to an empty dict.
44+
ws_filename : str, optional
45+
Filename for workspace storage. Defaults to ``'./workspace.mat'``.
46+
47+
Examples
48+
--------
49+
>>> m = MatlabProcess()
50+
51+
>>> m.start()
52+
>>> m.write_value('a', 37)
53+
>>> m.run_command('tf = isprime(a);')
54+
>>> m.read_workspace()
55+
>>> m.stop()
56+
>>> print(m.ws_data)
57+
58+
>>> m.write_value('a', 17)
59+
>>> m.run_command('res = isprime(a);')
60+
>>> m.read_value('res')
61+
True
62+
63+
>>> m.run_command('res = isprime(a);', ivars={'a': 17})
64+
>>> m.read_value('res')
65+
True
66+
67+
>>> m.run_command('res = isprime(a);', ivars={'a': 17}, ovars={'res': None})
68+
{'res': True}
6769
6870
"""
6971

‎src/compas/com/matlab_/session.py‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,27 +24,39 @@ def __init__(self, message=None):
2424
class MatlabSession(object):
2525
"""Communicate with Matlab through a shared session.
2626
27+
Parameters
28+
----------
29+
name : str
30+
Name of a running Matlab session.
31+
32+
Notes
33+
-----
2734
Note that the Matlab engine for Python is only available since R2014b.
2835
For earlier versions of Matlab, use ``MatlabProcess`` instead.
2936
30-
For more information,
31-
see `Connect Python to Running MATLAB Session <https://ch.mathworks.com/help/matlab/matlab_external/connect-python-to-running-matlab-session.html>`_
37+
For more information, see [1]_
38+
39+
References
40+
----------
41+
.. [1] MathWorks, 2017. *Connect Python to Running MATLAB Session*.
42+
Available at https://ch.mathworks.com/help/matlab/matlab_external/connect-python-to-running-matlab-session.html
3243
33-
Examples:
34-
>>> m = MatlabSession()
35-
>>> m.session_name
36-
'MATLAB_13404'
37-
>>> m.isprime(37)
38-
True
44+
Examples
45+
--------
46+
>>> m = MatlabSession()
47+
>>> m.session_name
48+
'MATLAB_13404'
49+
>>> m.isprime(37)
50+
True
3951
40-
.. code-block:: python
52+
.. code-block:: python
4153
42-
# execute `matlab -nosplash -r "matlab.engine.shareEngine('MATLAB_xxx')"`
43-
# to connect to an existing named session
54+
# execute `matlab -nosplash -r "matlab.engine.shareEngine('MATLAB_xxx')"`
55+
# to connect to an existing named session
4456
45-
>>> m = MatlabSession('MATLAB_xxx')
46-
>>> m.isprime(37)
47-
True
57+
>>> m = MatlabSession('MATLAB_xxx')
58+
>>> m.isprime(37)
59+
True
4860
4961
"""
5062

‎src/compas/com/rhino/client.py‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,17 +29,16 @@ class RhinoClientError(Exception):
2929
class RhinoClient(object):
3030
"""Communicate with Rhino through Window's COM interface.
3131
32-
Warning:
33-
This only works on Windows!
34-
35-
Parameters:
36-
delay_start (bool, optional) : Delay the creation of a COM interface.
37-
Default is ``False``.
38-
39-
Examples:
40-
>>> r = RhinoApp()
41-
>>> r.AddPoint(0, 0, 0)
42-
<guid>
32+
Parameters
33+
----------
34+
delay_start : bool, optional
35+
Delay the creation of a COM interface. Default is ``False``.
36+
37+
Examples
38+
--------
39+
>>> r = RhinoApp()
40+
>>> r.AddPoint(0, 0, 0)
41+
<guid>
4342
4443
"""
4544

‎src/compas/datastructures/__init__.py‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,75 @@
77
88
.. module:: compas.datastructures
99
10+
This package defines a mesh datastructure, a network, and a cellular mesh.
11+
12+
13+
Mesh
14+
====
15+
16+
The mesh is implemented as a half-edge datastructure.
17+
It is meant for the representation of polygonal *"surface"* meshes. A mesh can be
18+
connected or disconnected. A mesh can be closed or open. A mesh can be comprised
19+
of only vertices.
20+
21+
.. unified face orientation => consistent/compatible cycle directions
22+
.. vertex => neighbours => halfedges => faces (optionally ordered around vertex)
23+
.. face => vertices => halfedges => neighbours
24+
.. vertex => connectivity, area, normal, laplacian, ...
25+
.. face => area, normal, ...
1026
1127
.. autosummary::
1228
:toctree: generated/
1329
:nosignatures:
1430
1531
Mesh
32+
33+
34+
Network
35+
=======
36+
37+
The network is a connectivity graph.
38+
It is meant for the representation of networks of vertices connected by edges.
39+
The edges are directed. A network does not have faces. A network can be connected
40+
or disconnected. A network with vertices only is also a valid network.
41+
42+
.. vertex => neighbours, laplacian
43+
.. edge =>
44+
45+
.. form := network => ordering of neighbours is enough to construct dual
46+
.. force := mesh => with faces constructed from the ordering ov neighbours
47+
48+
.. autosummary::
49+
:toctree: generated/
50+
:nosignatures:
51+
1652
Network
53+
54+
55+
VolMesh
56+
=======
57+
58+
The volmesh is a cellular mesh. It is implemented as
59+
a half-plane, the three-dimensional equivalent of a half-edge. It can, for example,
60+
be used for the representation of subdivided/partitioned polyhedra.
61+
62+
63+
.. autosummary::
64+
:toctree: generated/
65+
:nosignatures:
66+
1767
VolMesh
1868
69+
70+
.. Assembly
71+
.. ========
72+
73+
.. .. autosummary::
74+
.. :toctree: generated/
75+
.. :nosignatures:
76+
77+
.. Assembly
78+
1979
"""
2080

2181
from __future__ import print_function

‎src/compas/datastructures/mesh/mesh.py‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -94,10 +94,6 @@ class Mesh(FromToJson,
9494
Datastructure):
9595
"""Definition of a mesh.
9696
97-
Note
98-
----
99-
The datastructure of the mesh is implemented as a half-edge.
100-
10197
Attributes
10298
----------
10399
vertex : dict

‎src/compas/datastructures/mesh/operations/collapse.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ def mesh_collapse_edge(self, u, v, t=0.5, allow_boundary=False, fixed=None):
6868
"""Collapse an edge to its first or second vertex, or to an intermediate
6969
point.
7070
71-
Note:
71+
Notes:
7272
An edge can only be collapsed if the collapse is `legal`. A collapse is
7373
legal if it meets the following requirements:
7474
@@ -219,8 +219,8 @@ def trimesh_collapse_edge(self, u, v, t=0.5, allow_boundary=False, fixed=None):
219219
"""Collapse an edge to its first or second vertex, or to an intermediate
220220
point.
221221
222-
Note
223-
----
222+
Notes
223+
-----
224224
An edge can only be collapsed if the collapse is `legal`. A collapse is
225225
legal if it meets the following requirements:
226226
@@ -252,8 +252,8 @@ def trimesh_collapse_edge(self, u, v, t=0.5, allow_boundary=False, fixed=None):
252252
ValueError
253253
If `u` and `v` are not neighbours.
254254
255-
Example
256-
-------
255+
Examples
256+
--------
257257
.. plot::
258258
:include-source:
259259

‎src/compas/datastructures/mesh/operations/split.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,12 +99,12 @@ def trimesh_split_edge(self, u, v, t=0.5, allow_boundary=False):
9999
allow_boundary : bool (False)
100100
Allow splits on boundary edges.
101101
102-
Note
103-
----
102+
Notes
103+
-----
104104
This operation only works as expected for triangle meshes.
105105
106-
Example
107-
-------
106+
Examples
107+
--------
108108
.. plot::
109109
:include-source:
110110

0 commit comments

Comments
 (0)