Skip to content

Commit 65ba938

Browse files
chinyeunglichinyeungli
committed
Review and update documentation
1 parent f6580e3 commit 65ba938

File tree

9 files changed

+217
-114
lines changed

9 files changed

+217
-114
lines changed

‎REFERENCE.rst‎

Lines changed: 157 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
1+
Reference
2+
=========
3+
14
about
2-
=====
5+
-----
36

47
**Syntax**
58

@@ -18,37 +21,46 @@ about
1821

1922
::
2023

21-
attrib LOCATION: directory, OUTPUT: output file
22-
check LOCATION: directory
23-
gen LOCATION: input file, OUTPUT: directory
24-
inventory LOCATION: directory, OUTPUT: csv file
25-
transform LOCATION: csv file, OUTPUT: csv file
24+
attrib Generate an attribution document from .ABOUT files.
25+
check Validate that the format of .ABOUT files is correct and
26+
report errors and warnings.
27+
collect_redist_src Collect redistributable sources.
28+
gen Generate .ABOUT files from an inventory as CSV or JSON.
29+
inventory Collect the inventory of .ABOUT files to a CSV or JSON
30+
file.
31+
transform Transform a CSV/JSON by applying renamings, filters and
32+
checks.
2633

2734

2835
attrib
29-
======
36+
------
3037

3138
**Syntax**
3239

3340
::
3441

3542
about attrib [OPTIONS] LOCATION OUTPUT
3643

37-
LOCATION: Path to an ABOUT file or a directory containing ABOUT files.
38-
OUTPUT: Path to output file to write the attribution to.
44+
LOCATION: Path to a file, directory or .zip archive containing .ABOUT
45+
files.
46+
47+
OUTPUT: Path where to write the attribution document.
3948

4049
**Options:**
4150

4251
::
4352

44-
--template PATH Path to a custom attribution template.
45-
--vartext <key>=<value> Variable text as key=value for use in a custom attribution template.
46-
--verbose Show all the errors and warning.
47-
-q, --quiet Do not print any error/warning.
48-
-h, --help Show this message and exit.
53+
--template FILE Path to an optional custom attribution template to
54+
generate the attribution document. If not provided
55+
the default built-in template is used.
56+
--vartext <key>=<value> Add variable text as key=value for use in a custom
57+
attribution template.
58+
-q, --quiet Do not print error or warning messages.
59+
--verbose Show all error and warning messages.
60+
-h, --help Show this message and exit.
4961

5062
Purpose
51-
-------
63+
^^^^^^^
5264
Generate an attribution file which contains the all license information
5365
from the LOCATION along with the license text.
5466

@@ -64,7 +76,7 @@ Assume the following:
6476
$ about attrib /home/about_files/ /home/attribution/attribution.html
6577

6678
Options
67-
-------
79+
^^^^^^^
6880

6981
::
7082

@@ -84,7 +96,7 @@ Options
8496

8597
Users can use the following in the template to get the vartext:
8698
{{ variables['title'] }}
87-
{{ variables['header'] }}
99+
{{ variables['header'] }}
88100

89101
--verbose
90102

@@ -95,13 +107,23 @@ Options
95107
The following data are passed to jinja2 and, therefore, can be used for a custom template:
96108
* about object: the about objects
97109
* common_licenses: a common license keys list in licenses.py
98-
* license_key_and_context: a dictionary list with license_key as a key and license text as the value
99-
* license_file_name_and_key: a dictionary list with license file name as a key and license key as the value
100-
* license_key_to_license_name: a dictionary list with license key as a key and license file name as the value
110+
* license_file_key_and_context: a dictionary with license_file_key (It's basically
111+
a license_key if it's not a custom license or license file name otherwise) as a key
112+
and license text as the value
113+
* license_file_key_and_license_key: a dictionary with license file key as a key
114+
and license key as the value
115+
* license_file_name_and_license_file_key: a dictionary with license file name as
116+
a key and license file key as the value
117+
* license_key_and_license_file_name: a dictionary with license key as a key
118+
and license file name as the value
119+
* license_key_and_license_name: a dictionary with license key as a key and
120+
license name as the value
121+
* license_name_and_license_key: a dictionary with license name as a key and
122+
license key as the value
101123

102124

103125
check
104-
=====
126+
-----
105127

106128
**Syntax**
107129

@@ -119,11 +141,11 @@ check
119141
-h, --help Show this message and exit.
120142

121143
Purpose
122-
-------
144+
^^^^^^^
123145
Validating ABOUT files at LOCATION.
124146

125147
Options
126-
-------
148+
^^^^^^^
127149

128150
::
129151

@@ -135,8 +157,80 @@ Options
135157
$ about check --verbose /home/project/about_files/
136158

137159

160+
collect_redist_src
161+
------------------
162+
163+
**Syntax**
164+
165+
::
166+
167+
about collect_redist_src [OPTIONS] LOCATION OUTPUT
168+
169+
LOCATION: Path to a directory containing sources that need to be copied
170+
(and containing ABOUT files if `inventory` is not provided)
171+
172+
OUTPUT: Path to a directory or a zip file where sources will be copied to.
173+
174+
**Options:**
175+
176+
::
177+
178+
--from-inventory FILE Path to an inventory CSV/JSON file as the base list
179+
for files/directories that need to be copied which
180+
have the 'redistribute' flagged.
181+
--with-structures Copy sources with directory structure.
182+
--zip Zip the copied sources to the output location.
183+
-q, --quiet Do not print error or warning messages.
184+
--verbose Show all error and warning messages.
185+
-h, --help Show this message and exit.
186+
187+
Purpose
188+
^^^^^^^
189+
Collect sources that have 'redistribute' flagged as 'True' in .ABOUT files or inventory to the output location.
190+
191+
Options
192+
^^^^^^^
193+
194+
::
195+
196+
--from-inventory
197+
198+
Provide an inventory CSV/JSON file with the 'redistribute' field filled as
199+
the indication of which files/sources need to be copied.
200+
201+
$ about collect_redist_src --from-inventory 'path to the inventory' LOCATION OUTPUT
202+
203+
--with-structures
204+
205+
Copy the file(s) along with its parent directories
206+
207+
For instance, assuming we want to copy the following file:
208+
/project/work/hello/foo.c
209+
210+
OUTPUT: /output/
211+
212+
$ about collect_redist_src --with-structure /project/ /output/
213+
214+
OUTPUT: /output/work/hello/foo.c
215+
216+
$ about collect_redist_src /project/ /output/
217+
218+
OUTPUT: /output/foo.c
219+
220+
--zip
221+
222+
Zip the copied sources to the output location
223+
224+
$ about collect_redist_src --zip /project/ /output/output.zip
225+
226+
--verbose
227+
228+
This option tells the tool to show all errors found.
229+
The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'
230+
231+
138232
gen
139-
===
233+
---
140234

141235
**Syntax**
142236

@@ -169,16 +263,16 @@ gen
169263
about gen --fetch-license 'api_url' 'api_key'
170264
--reference PATH Path to a directory with reference license
171265
data and text files.
172-
--verbose Show all the errors and warning.
173266
-q, --quiet Do not print any error/warning.
267+
--verbose Show all the errors and warning.
174268
-h, --help Show this message and exit.
175269

176270
Purpose
177-
-------
178-
Given an inventory of ABOUT files at location, generate ABOUT files in base directory.
271+
^^^^^^^
272+
Given a CSV/JSON inventory, generate ABOUT files in the output location.
179273

180274
Options
181-
-------
275+
^^^^^^^
182276

183277
::
184278

@@ -195,8 +289,8 @@ Options
195289

196290
--fetch-license
197291

198-
Fetch licenses text from a DejaCode API. and create <license>.LICENSE side-by-side
199-
with the generated .ABOUT file using data fetched from the DejaCode License Library.
292+
Fetch licenses text from a DejaCode API, and create <license>.LICENSE side-by-side
293+
with the generated .ABOUT file using the data fetched from the DejaCode License Library.
200294

201295
This option requires 2 parameters:
202296
api_url - URL to the DJE License Library.
@@ -217,7 +311,7 @@ Options
217311
/home/licenses_notices/apache2.LICENSE
218312
/home/licenses_notices/jquery.js.NOTICE
219313

220-
$ about gen --license-notice-text-location /home/licenses_notices/ LOCATION OUTPUT
314+
$ about gen --reference /home/licenses_notices/ LOCATION OUTPUT
221315

222316
--verbose
223317

@@ -226,7 +320,7 @@ Options
226320

227321

228322
inventory
229-
=========
323+
---------
230324

231325
**Syntax**
232326

@@ -242,23 +336,21 @@ inventory
242336
::
243337

244338
-f, --format [json|csv] Set OUTPUT file format. [default: csv]
245-
--verbose Show all the errors and warning.
246339
-q, --quiet Do not print any error/warning.
340+
--verbose Show all the errors and warning.
247341
-h, --help Show this message and exit.
248342

249343
Purpose
250-
-------
251-
Collect a JSON or CSV inventory of components from ABOUT files.
344+
^^^^^^^
345+
Create a JSON or CSV inventory of components from ABOUT files.
252346

253347
Options
254-
-------
348+
^^^^^^^
255349

256350
::
257351

258-
The above command will only inventory the ABOUT files which have the "license_expression: gpl-2.0"
259-
260352
-f, --format [json|csv]
261-
353+
262354
Set OUTPUT file format. [default: csv]
263355

264356
$ about inventory -f json LOCATION OUTPUT
@@ -270,17 +362,17 @@ Options
270362

271363

272364
Special Notes
273-
=============
365+
-------------
274366
Multiple licenses support format
275-
--------------------------------
367+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
276368
The multiple licenses support format for CSV files are separated by line break
277369

278-
+----------------+------+-----------------+----------------------+
279-
| about_resource | name | license_key | license_file |
280-
+----------------+------+-----------------+----------------------+
281-
| test.tar.xz | test | | apache-2.0 | | apache-2.0.LICENSE |
282-
| | | | mit | | mit.LICENSE |
283-
+----------------+------+-----------------+----------------------+
370+
+----------------+------+---------------+---------------+----------------------+
371+
| about_resource | name | license_key | license_name | license_file |
372+
+----------------+------+---------------+---------------+----------------------+
373+
| test.tar.xz | test | | apache-2.0 | | Apache 2.0 | | apache-2.0.LICENSE |
374+
| | | | mit | | MIT License | | mit.LICENSE |
375+
+----------------+------+---------------+---------------+----------------------+
284376

285377

286378
The multiple licenses support format for ABOUT files are by "grouping" with the keyword "licenses"
@@ -291,13 +383,15 @@ The multiple licenses support format for ABOUT files are by "grouping" with the
291383
name: test
292384
licenses:
293385
- key: apache 2.0
386+
name: Apache 2.0
294387
file: apache-2.0.LICENSE
295388
- key: mit
389+
name: MIT License
296390
file: mit.LICENSE
297391

298392

299-
Multiple license_file support
300-
-----------------------------
393+
Multiple license_file support
394+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
301395
To support multiple license file for a license, the correct format is to separate by comma
302396

303397
+----------------+------+-----------------+----------------------+
@@ -315,22 +409,26 @@ To support multiple license file for a license, the correct format is to separat
315409
name: test
316410
licenses:
317411
- key: gpl-2.0
412+
name: gpl-2.0
318413
file: COPYING, COPYING.v2
319414
- key: mit
415+
name: mit
320416
file: mit.LICENSE
321417

418+
Note that if `license_name` is not provided, the license key will be used as the
419+
license name.
322420

323421
transform
324-
=========
422+
---------
325423

326424
**Syntax**
327425

328426
::
329427

330428
about transform [OPTIONS] LOCATION OUTPUT
331429

332-
LOCATION: Path to a CSV file.
333-
OUTPUT: Path to CSV inventory file to create.
430+
LOCATION: Path to a CSV/JSON file.
431+
OUTPUT: Path to CSV/JSON inventory file to create.
334432

335433
**Options:**
336434

@@ -344,11 +442,13 @@ transform
344442
-h, --help Show this message and exit.
345443

346444
Purpose
347-
-------
348-
Transform the CSV file at LOCATION by applying renamings, filters and checks and write a new CSV to OUTPUT.
445+
^^^^^^^
446+
Transform the CSV/JSON file at LOCATION by applying renamings, filters and checks
447+
and then write a new CSV/JSON to OUTPUT (Format for input and output need to be
448+
the same).
349449

350450
Options
351-
-------
451+
^^^^^^^
352452

353453
::
354454

@@ -362,7 +462,7 @@ Options
362462

363463
Show configuration file format help and exit.
364464
This option will print out examples of the the YAML configuration file.
365-
465+
366466
Keys configuration are: `field_renamings`, `required_fields` and `field_filters`
367467

368468
$ about transform --help-format
@@ -373,6 +473,6 @@ Options
373473
The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'
374474

375475
Special Notes
376-
=============
476+
-------------
377477
When using the `field_filters` configuration, all the standard required columns
378478
(`about_resource` and `name`) and the user defined `required_fields` need to be included.

0 commit comments

Comments
 (0)