Skip to content

Commit d8fc729

Browse files
chinyeunglichinyeungli
committed
Fixed #84
Created an EXAMPLES which have a detail explaination of each scripts and options.
1 parent 2de0851 commit d8fc729

File tree

1 file changed

+228
-0
lines changed

1 file changed

+228
-0
lines changed

‎EXAMPLES‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
========
2+
about.py
3+
========
4+
5+
------
6+
Syntax
7+
------
8+
9+
Usage: about.py [options] input_path output_path
10+
11+
Input can be a file or directory.
12+
Output must be a file with a .csv extension.
13+
14+
Options:
15+
-h, --help Display help
16+
--version Display current version, license notice, and copyright notice
17+
--overwrite Overwrites the output file if it exists
18+
--verbosity=VERBOSITY
19+
Print more or fewer verbose messages while processing ABOUT files
20+
0 - Do not print any warning or error messages, just a total count (default)
21+
1 - Print error messages
22+
2 - Print error and warning messages
23+
24+
-------
25+
Purpose
26+
-------
27+
28+
Extract information from the .ABOUT files and save it to the CSV file.
29+
30+
-------
31+
Options
32+
-------
33+
34+
--overwrite
35+
36+
Overwrite the extracted data from .ABOUT files to the output location
37+
38+
$ python about.py --overwrite <input path> <output path>
39+
40+
41+
===========
42+
genabout.py
43+
===========
44+
45+
------
46+
Syntax
47+
------
48+
49+
Usage: genabout.py [options] input_path output_path
50+
51+
Input must be a CSV file
52+
Output must be a directory location where the ABOUT files should be generated
53+
54+
55+
Options:
56+
-h, --help Display help
57+
--version Display current version, license notice, and copyright notice
58+
--verbosity=VERBOSITY
59+
Print more or fewer verbose messages while processing ABOUT files
60+
0 - Do not print any warning or error messages, just a total count (default)
61+
1 - Print error messages
62+
2 - Print error and warning messages
63+
64+
--action=ACTION Handle different behaviors if ABOUT files already existed
65+
0 - Do nothing if ABOUT file existed (default)
66+
1 - Overwrites the current ABOUT field value if existed
67+
2 - Keep the current field value and only add the "new" field and field value
68+
3 - Replace the ABOUT file with the current generation
69+
70+
--all_in_one Generate all the ABOUT files in the [output_path] without
71+
any project structure
72+
73+
--copy_license=COPY_LICENSE
74+
Copy the 'license_text_file' from the project to the generated location
75+
Project path - Project path
76+
77+
--license_text_location=LICENSE_TEXT_LOCATION
78+
Copy the 'license_text_file' from the directory to the generated location
79+
License path - License text files path
80+
81+
--mapping Configure the mapping key from the MAPPING.CONFIG
82+
83+
--extract_license=EXTRACT_LICENSE
84+
Extract License text and create <license_key>.LICENSE side-by-side
85+
with the .ABOUT from DJE License Library.
86+
api_url - URL to the DJE License Library
87+
api_username - The regular DJE username
88+
api_key - Hash attached to your username which is used to authenticate
89+
yourself in the API. Contact us to get the hash key.
90+
91+
Example syntax:
92+
genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key'
93+
94+
-------
95+
Purpose
96+
-------
97+
98+
Generate ABOUT files from the input CSV file to output location
99+
100+
-------
101+
Options
102+
-------
103+
104+
--action=ACTION
105+
106+
Handle different behaviors if ABOUT files already existed.
107+
For instance, replace the ABOUT files with the current generation
108+
109+
$ python genabout.py --action=3 <input path> <output path>
110+
111+
--all_in_one
112+
113+
Generate all the ABOUT files to the output location without any project structure
114+
115+
$ python genabout.py --all_in_one <input path> <output path>
116+
117+
--copy_license
118+
119+
Copy the license files to the generated location based on the
120+
'license_text_file' value in the input from the project
121+
122+
Purpose of this option is for users who want to generate ABOUT files
123+
in a different location other than the project side by side with the code.
124+
125+
For instance, the project is located at /home/project/, and users want to
126+
generate ABOUT files to /home/about/ and also want to copy the licenses from
127+
/home/project/ to /home/about/
128+
129+
$ python genabout.py --copy_license=/home/project/ <input path> /home/about/
130+
131+
--license_text_location
132+
133+
Copy the license files to the generated location based on the
134+
'license_text_file' value in the input from the directory
135+
136+
For instance,
137+
the directory, /home/licenses/, contains all the licenses that users want:
138+
/home/license/apache2.LICENSE
139+
/home/license/jquery.js.LICENSE
140+
141+
$ python genabout.py --license_text_location=/home/licenses/ <input path> <output path>
142+
143+
--mapping
144+
145+
This tool needs the input CSV to have the required and/or optional keys to work.
146+
By understanding the user's input may not have the same keys name as the tool use,
147+
there are two ways the users can do.
148+
1. Change the keys name directly in the input manually.
149+
2. Use the '--mapping' option to configure the keys mapping.
150+
151+
When the '--mapping' is set, this tool will look into the 'MAPPING.CONFIG'
152+
and do the keys mapping.
153+
154+
For instance, assuming the context of the MAPPING.CONFIG is the following:
155+
about_resource: file_name
156+
about_file: Resource
157+
name: Component
158+
version: file_version
159+
160+
This tool will look into the input CSV and try to find the column key named
161+
'file_name' and configure to map with the 'about_resource' key that this
162+
tool use. The 'Resource' will then configure to map with 'about_file' and
163+
so on.
164+
165+
In another word, users do not need to modify the keys name of the
166+
input manually but let the 'MAPPING.CONFIG' to do the keys mapping.
167+
168+
$ python genabout.py --mapping <input path> <output path>
169+
170+
--extract_license
171+
172+
Extract license text(s) from DJE License Library and create
173+
<license_key>.LICENSE side-by-side with the generated .ABOUT files based
174+
on the 'dje_license' value in the input CSV.
175+
176+
This option requires 3 parameters:
177+
api_url - URL to the DJE License Library
178+
api_username - The regular DJE username
179+
api_key - Hash attached to your username which is used to authenticate
180+
yourself in the API.
181+
(Please contact us to get the api_* value to use this feature)
182+
183+
genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key' <input path> <output path>
184+
185+
186+
============
187+
genattrib.py
188+
============
189+
190+
------
191+
Syntax
192+
------
193+
194+
Usage: genattrib.py [options] input_path output_path component_list
195+
196+
Input can be a file or directory.
197+
Output of rendered template must be a file (e.g. .html).
198+
Component List must be a .csv file which has at least an "about_resource" column.
199+
200+
201+
Options:
202+
-h, --help Display help
203+
-v, --version Display current version, license notice, and copyright notice
204+
--overwrite Overwrites the output file if it exists
205+
--verbosity=VERBOSITY
206+
Print more or fewer verbose messages while processing ABOUT files
207+
0 - Do not print any warning or error messages, just a total count (default)
208+
1 - Print error messages
209+
2 - Print error and warning messages
210+
211+
-------
212+
Purpose
213+
-------
214+
215+
Generate an Attribution HTML file which contains the license information from
216+
the 'component_list' along with the license text.
217+
218+
This tool will look at the components in the 'component_list' and find the
219+
corresponding .ABOUT files in the 'input_path' and generate the output in
220+
the 'output_path'. Therefore, please make sure there are .ABOUT files under
221+
the 'input_path'.
222+
223+
Assuming the follow:
224+
'/home/about_files/' contains all the ABOUT files from the component_list
225+
'/home/attribution/attribution.html' is the user's output path
226+
'/home/project/component_list.csv' is the component list that user want to be generated
227+
228+
$ python genattrib.py /home/about_files/ /home/attribution/attribution.html /home/project/component_list.csv

0 commit comments

Comments
 (0)