You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 19, 2025. It is now read-only.
Closes#1264.
### Summary of Changes
Build documentation site and upload it to Read the Docs.
---------
Co-authored-by: lars-reimann <[email protected]>
@@ -17,7 +17,7 @@ The automation described above relies on structured information about the existi
17
17
```
18
18
4. Open [localhost:4280](http://localhost:4280) in your browser.
19
19
5. In the window that opens, enter your username in the bottom right field.
20
-
6. Download the contents of the [`data`](data) folder of this project. Alternatively, compute the required data for another Python API using the [package-parser][package-parser].
20
+
6. Download the contents of the [`data`][data] folder of this project. Alternatively, compute the required data for another Python API using the [package-parser][package-parser].
21
21
7. Open `File > Import > API Data` and upload the API data that you stored locally.
22
22
8. Open `File > Import > Usages` and upload the usage data that you stored locally.
23
23
9. Open `File > Import > Annotations` and upload the annotation data that you stored locally (from the repository or your own prior usages of the tool).
@@ -48,6 +48,7 @@ Now you are ready to explore the API and review existing annotations.
48
48
```
49
49
3. Open [localhost:5173](http://localhost:5173) in your browser.
The purpose of the _api-editor_ is to manually annotate classes, functions, and parameters from a given API
4
6
to generate an improved API. The _package-parser_, in contrast, marks annotations automatically.
5
7
These annotations can be imported, edited and deleted in the _api-editor_.
6
8
7
9
## Import
8
-
Before you can start adding own annotations, you need to import the [generated API, usages and annotations files](../package-parser/README.md) from _package-parser_.
9
10
10
-
<imgsrc="img/import.jpg"alt="Import API Data">
11
+
Before you can start adding own annotations, you need to import the [generated API, usages and annotations files](package-parser/README.md) from _package-parser_.
12
+
13
+
11
14
12
15
Now you can select packages, classes, functions, or parameters from the tree view on the right side and see the further information (documentation, annotation, etc.) about the selected element on the left side.
13
16
14
17
## Annotations
18
+
15
19
An improved API is created through annotations.
16
20
_Package-parser_ automatically generates some types of annotations by the documentation and the number of calls.
17
21
These are `Boundary`, `Constant`, `Enum`, `Optional`, `Remove`, and `Required`.
18
22
The other annotations cannot be generated, but are set manually with _api-editor_.
19
23
20
-
<imgsrc="img/annotation.jpg"alt="Creation of a new annotation"style="max-width: 800px;">
24
+
21
25
22
26
To add new annotations, select the corresponding class, function, or parameter in the tree view
23
27
and choose the desired annotation from the drop-down menu on the left.
@@ -26,96 +30,108 @@ To edit an annotation, click on the annotation in the selected component of the
26
30
and to delete it, click on the red trash button on the right side of the annotation panel.
27
31
28
32
### List of annotations and their meaning
29
-
*### Boundary
30
-
The annotation is used for numerical parameters, that should be in a specific range.
31
-
The interval can be open or closed, and can have no upper or lower limit.
32
-
_Continuous_ or _Discrete_ refers to the set of real numbers or integers.
33
33
34
-
<imgsrc="img/boundary.jpg"alt="Edit a boundary annotation"style="max-width: 450px;">
34
+
-### Boundary
35
+
The annotation is used for numerical parameters, that should be in a specific range.
36
+
The interval can be open or closed, and can have no upper or lower limit.
37
+
_Continuous_ or _Discrete_ refers to the set of real numbers or integers.
38
+
39
+
40
+
41
+
-### CalledAfter
42
+
43
+
When a function may only be called after another function, it should be marked with a CalledAfter annotation.
44
+
The two functions must be in the same class.
45
+
46
+
-### Constant
47
+
Parameters that are assigned only one value are marked with this annotation.
48
+
The function `f(x, y)` where x has a constant annotation will be a local variable with the result that `f(y)` has one parameter less.
49
+
Permitted types are primitive data types or None.
35
50
36
-
*### CalledAfter
37
-
When a function may only be called after another function, it should be marked with a CalledAfter annotation.
38
-
The two functions must be in the same class.
51
+
39
52
40
-
*### Constant
41
-
Parameters that are assigned only one value are marked with this annotation.
42
-
The function ``f(x, y)`` where x has a constant annotation will be a local variable with the result that ``f(y)`` has one parameter less.
43
-
Permitted types are primitive data types or None.
53
+
-### Enum
54
+
The annotation is for string parameters that require specific words as input, and they should be converted to an enum.
55
+
Its elements contain a string value which is the value of the parameter and an instance name for the name of the element.
44
56
45
-
<imgsrc="img/constant.jpg"alt="Add a constant annotation"style="max-width: 450px;">
57
+
46
58
59
+
-### Group
60
+
A group annotation is applicable on a function, but user-defined parameters are grouped into a single parameter in the enhanced API.
61
+
For that purpose, a new class with the selected parameters will be created.
62
+
The list of parameters of the method will contain the not selected parameters and one from the type of the new created class.
47
63
48
-
*### Enum
49
-
The annotation is for string parameters that require specific words as input, and they should be converted to an enum.
50
-
Its elements contain a string value which is the value of the parameter and an instance name for the name of the element.
64
+
51
65
52
-
<imgsrc="img/enum.jpg"alt="Edit an enum annotation"style="max-width: 450px;">
66
+
-### Move
53
67
54
-
*### Group
55
-
A group annotation is applicable on a function, but user-defined parameters are grouped into a single parameter in the enhanced API.
56
-
For that purpose, a new class with the selected parameters will be created.
57
-
The list of parameters of the method will contain the not selected parameters and one from the type of the new created class.
68
+
Classes with this annotation will be moved to a custom module.
58
69
59
-
<imgsrc="img/group.jpg"alt="Add a group annotation"style="max-width: 500px;">
70
+
-### Optional
60
71
61
-
*### Move
62
-
Classes with this annotation will be moved to a custom module.
72
+
A new default value for the parameter should be added. e.g, The function `f(x=1)` would be converted to `f(x)`.
63
73
64
-
*### Optional
65
-
A new default value for the parameter should be added. e.g, The function ``f(x=1)`` would be converted to ``f(x)``.
74
+
-### Pure
66
75
67
-
*### Pure
68
-
This annotation applies to functions that have no side effects and whose return value is the same if the parameters passed in the calls are the same.
69
-
An invocation of such a function can be deleted if the return value isn't assigned.
70
-
The second attribute allows the function to be cached.
76
+
This annotation applies to functions that have no side effects and whose return value is the same if the parameters passed in the calls are the same.
77
+
An invocation of such a function can be deleted if the return value isn't assigned.
78
+
The second attribute allows the function to be cached.
71
79
72
-
*### Remove
73
-
A class or a function that is marked with this annotation should be removed.
80
+
-### Remove
74
81
75
-
*### Rename
76
-
This annotation renames a class, function, or parameter.
82
+
A class or a function that is marked with this annotation should be removed.
77
83
78
-
*### Required
79
-
An optional Parameter should be required. It is the opposite action of [Optional](#optional).
84
+
-### Rename
85
+
86
+
This annotation renames a class, function, or parameter.
87
+
88
+
-### Required
89
+
An optional Parameter should be required. It is the opposite action of [Optional](#optional).
80
90
81
91
## Features
92
+
82
93
There are features for a better overview of the API and its usages.
83
94
84
95
### Filter
96
+
85
97
For a better listing, there is a text box filter in the top right corner that can filter the elements of the API.
86
98
The available commands for filtering are displayed when you press the help button on its right side.
87
-
If an ``!`` is before a command, it negates that filter.
99
+
If an `!` is before a command, it negates that filter.
88
100
Multiple commands are interpreted as an and operation.
89
101
The elements that meet the filter are printed in bold in the tree view.
90
102
91
-
<imgsrc="img/filter.jpg"alt="Filter for 'is:public name:x is:parameter' is set and the help panel for filtering is open"style="max-height: 650px;">
103
+
92
104
93
105
### Heat Map
106
+
94
107
To get a heat map for the number of annotations or calls, go to Settings → Heat Map Mode and click on the desired view.
95
108
There are two options for the number of times the API is used.
96
109
_Usages_ shows the total number of calls and _usefullness_ subtract out the internal calls.
97
110
The third option is for the number of annotations that a class, function, or parameter has.
98
111
99
-
<imgsrc="img/heat_map.jpg"alt="In the tree view, the heat map is activated and in the menu bar, the drop-down menu of Settings is open and ''Usefulness'' is selected."style="max-height: 650px;">
112
+
100
113
101
114
In the tree view of all components of the API,
102
115
the number of uses or the number of annotations of an individual component is color-coded in a box to the left of its name.
103
116
The warmer the color of the box, the more often the component is used or the more annotations it has.
104
117
The absolute number can be found in the box.
105
118
106
119
### Navigation bar
107
-
<imgsrc="img/navigation.jpg"alt="Navigation bar with the buttons: previous, next, expand / collapse all, expand / collapse selected">
120
+
121
+
108
122
109
123
At the bottom right is a panel with six buttons for better handling of the tree view:
110
124
_Previous_ and _Next_ select the previous or next item in the tree view that meet the [filter](#filter).
111
125
The other four buttons expand or collapse the entire tree view or only the selected element and all elements contained in it recursively.
112
126
113
127
### Delete all annotations
128
+
114
129
On the menu bar is a button to delete all annotations. Use this button wisely, or export the annotations (File → Export → Annotations) before proceeding.
115
130
116
131
## Generate API
132
+
117
133
The button _Generate adapters_ creates the improved API.
118
134
If there are any conflicts with annotations, they will be displayed and a new API won't be generated.
119
135
e.g, a module cannot have the annotations remove and move. One of them should be removed.
120
136
After generation, you can select the folder in which the file is to be stored.
121
-
It is a zip file with two folders. They are _adapter_ which contains the new API and [_stub_](https://github.com/lars-reimann/safe-data-science/blob/main/docs/DSL/stub-language/README.md).
137
+
It is a zip file with two folders. They are _adapter_ which contains the new API and stubs.
0 commit comments