Skip to content

Commit 819e87d

Browse files
chinyeunglichinyeungli
committed
Format docs to satisy the doc8 validation
Signed-off-by: Chin Yeung Li <tli@nexb.com>
1 parent 1519a41 commit 819e87d

30 files changed

+2419
-1930
lines changed

‎docs/source/aboutcode-data/abcd.rst‎

Lines changed: 421 additions & 432 deletions
Large diffs are not rendered by default.

‎docs/source/archive/contributor_project_ideas.rst‎

Lines changed: 197 additions & 177 deletions
Large diffs are not rendered by default.

‎docs/source/archive/gsoc-toc.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
GSoC -- Google Summer of Code
33
=============================
44

5-
**Google Summer of Code** is a global annual program focused on introducing students to
6-
open source software development. GSoC is completely online designed to encourage university
7-
student participation in open source software development.
8-
It was started by Google in 2005.
9-
More about GSoC - `<https://summerofcode.withgoogle.com/about/>`_
5+
**Google Summer of Code** is a global annual program focused on introducing
6+
students to open source software development. GSoC is completely online
7+
designed to encourage university student participation in open source
8+
software development. It was started by Google in 2005. More about GSoC -
9+
`<https://summerofcode.withgoogle.com/about/>`_
1010

1111
GSoC 2024
1212
---------

‎docs/source/archive/gsoc/org_pages/gsoc_2017.rst‎

Lines changed: 157 additions & 118 deletions
Large diffs are not rendered by default.

‎docs/source/archive/gsoc/org_pages/gsoc_2019.rst‎

Lines changed: 198 additions & 178 deletions
Large diffs are not rendered by default.

‎docs/source/archive/gsoc/reports/2017/scancode_toolkit_yash.rst‎

Lines changed: 74 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -9,120 +9,138 @@ Yash D. Saraf `yashdsaraf@gmail.com <mailto:yashdsaraf@gmail.com>`_
99
----
1010

1111
This project's purpose was to create a decoupled plugin architecture for
12-
`ScanCode <https://github.com/nexB/scancode-toolkit>`_ such that it can handle plugins at different
13-
stages of a scan and can be coupled at runtime. These stages were,
12+
`ScanCode <https://github.com/nexB/scancode-toolkit>`_ such that it can
13+
handle plugins at different stages of a scan and can be coupled at runtime.
14+
These stages were,
1415

1516
1. `Format <https://github.com/nexB/scancode-toolkit/issues/639>`_ :
1617
---------------------------------------------------------------------
1718

18-
In this stage, the plugins are supposed to run **after** the scanning is done and ``post-scan``
19-
plugins are called. These plugins could be used for:
19+
In this stage, the plugins are supposed to run **after** the scanning is
20+
done and ``post-scan`` plugins are called. These plugins could be used for:
2021

2122

22-
- **converting the scanned output to the given format (say csv, json, etc.)**
23+
- **converting the scanned output to the given format (say csv, json,
24+
etc.)**
2325

2426
**HOWTO**
2527

26-
Here, a plugin needs to add an entry in the ``scancode_output_writers`` entry point in the following
27-
format : ``'<format> = <module>:<function>'``.
28+
Here, a plugin needs to add an entry in the ``scancode_output_writers``
29+
entry point in the following format : ``'<format> = <module>:<function>'``.
2830

2931

30-
- ``<format>`` is the format name which will be used as the command line option name
31-
(e.g ``csv`` or ``json`` ).
32-
- ``<module>`` is a python module which implements the ``output`` hook specification.
33-
- ``<function>`` is the function to which the scan output will be passed if this plugin is called.
32+
- ``<format>`` is the format name which will be used as the command line
33+
option name (e.g ``csv`` or ``json`` ).
34+
- ``<module>`` is a python module which implements the ``output`` hook
35+
specification.
36+
- ``<function>`` is the function to which the scan output will be passed if
37+
this plugin is called.
3438

35-
The ``<format>`` name will be automatically added to the ``--format`` command line option and
36-
(if called) the scanned data will be passed to the plugin.
39+
The ``<format>`` name will be automatically added to the ``--format``
40+
command line option and (if called) the scanned data will be passed to the
41+
plugin.
3742

3843
2. `Post-scan <https://github.com/nexB/scancode-toolkit/issues/704>`_ :
3944
------------------------------------------------------------------------
4045

41-
In this stage, the plugins are supposed to run **after** the scanning is done. Some uses for these
42-
plugins were:
46+
In this stage, the plugins are supposed to run **after** the scanning is
47+
done. Some uses for these plugins were:
4348

4449

4550
- **summarization of scan outputs**
4651

47-
e.g A post-scan plugin for marking ``is_source`` to true for directories with ~90% of source
48-
files.
52+
e.g A post-scan plugin for marking ``is_source`` to true for
53+
directories with ~90% of source files.
4954

5055
- **simplification of scan outputs**
5156

52-
e.g The ``--only-findings`` option to return files or directories with findings for the
53-
requested scans. Files and directories without findings are omitted (not considering basic file
54-
information as findings)).
57+
e.g The ``--only-findings`` option to return files or directories with
58+
findings for the requested scans. Files and directories without
59+
findings are omitted (not considering basic file information as
60+
findings)).
5561

5662
This option already existed, I just ported it to a post-scan plugin.
5763

5864
**HOWTO**
5965

60-
Here, a plugin needs to add an entry in the ``scancode_post_scan`` entry point in the following
61-
format ``'<name> = <module>:<function>'``
66+
Here, a plugin needs to add an entry in the ``scancode_post_scan`` entry
67+
point in the following format ``'<name> = <module>:<function>'``
6268

6369
- ``<name>`` is the command line option name (e.g **only-findings**).
64-
- ``<module>`` is a python module which implements the ``post_scan`` hook specification.
65-
- ``<function>`` is the function to which the scanned files will be passed if this plugin is called
70+
- ``<module>`` is a python module which implements the ``post_scan`` hook
71+
specification.
72+
- ``<function>`` is the function to which the scanned files will be passed
73+
if this plugin is called
6674

67-
The command line option for this plugin will be automatically created using the ``<function>`` 's
68-
doctring as its help text and (if called) the scanned files will be passed to the plugin.
75+
The command line option for this plugin will be automatically created using
76+
the ``<function>`` 's doctring as its help text and (if called) the scanned
77+
files will be passed to the plugin.
6978

7079
3. `Pre-scan <https://github.com/nexB/scancode-toolkit/issues/719>`_ :
7180
-----------------------------------------------------------------------
7281

73-
In this stage, the plugins are supposed to run **before** the scan starts. So the potential uses
74-
for these types of plugins were to:
82+
In this stage, the plugins are supposed to run **before** the scan starts.
83+
So the potential uses for these types of plugins were to:
7584

7685
- **ignore files based on a given pattern (glob)**
7786
- **ignore files based on their info i.e size, type etc.**
7887
- **extract archives before scanning**
7988

8089
**HOWTO**
8190

82-
Here, a plugin needs to add an entry in the ``scancode_pre_scan`` entry point in the following
83-
format : ``'<name> = <module>:<class>'``
91+
Here, a plugin needs to add an entry in the ``scancode_pre_scan`` entry
92+
point in the following format : ``'<name> = <module>:<class>'``
8493

8594

8695
* ``<name>`` is the command line option name (e.g **ignore** ).
87-
* ``<module>`` is a python module which implements the ``pre_scan`` hook specification.
88-
* ``<class>`` is the class which is instantiated and its appropriate method is invoked if this
89-
plugin is called. This needs to extend the ``plugincode.pre_scan.PreScanPlugin`` class.
90-
91-
The command line option for this plugin will be automatically created using the ``<class>`` 's
92-
doctring as its help text. Since there isn't a single spot where ``pre-scan`` plugins can be
93-
plugged in, more methods to ``PreScanPlugin`` class can be added which can represent different
94-
hooks, say to add or delete a scan there might be a method called ``process_scan``.
95-
96-
If a plugin's option is passed by the user, then the ``<class>`` is instantiated with the user
97-
input and its appropriate aforementioned methods are called.
96+
* ``<module>`` is a python module which implements the ``pre_scan`` hook
97+
specification.
98+
* ``<class>`` is the class which is instantiated and its appropriate method
99+
is invoked if this plugin is called. This needs to extend the
100+
``plugincode.pre_scan.PreScanPlugin`` class.
101+
102+
The command line option for this plugin will be automatically created using
103+
the ``<class>`` 's doctring as its help text. Since there isn't a single
104+
spot where ``pre-scan`` plugins can be plugged in, more methods to
105+
``PreScanPlugin`` class can be added which can represent different hooks,
106+
say to add or delete a scan there might be a method called
107+
``process_scan``.
108+
109+
If a plugin's option is passed by the user, then the ``<class>`` is
110+
instantiated with the user input and its appropriate aforementioned methods
111+
are called.
98112

99113
4. Scan (proper):
100114
-----------------
101115

102-
In this stage, the plugins are supposed to run **before** the scan starts and **after** the
103-
``pre-scan`` plugins are called. These plugins would have been used for
116+
In this stage, the plugins are supposed to run **before** the scan starts
117+
and **after** the ``pre-scan`` plugins are called. These plugins would have
118+
been used for
104119

105120
- **adding or deleting scans**
106121
- **adding dependency scans (whose data could be used in other scans)**
107122

108-
No development has been done for this stage, but it will be quite similar to ``pre-scan``.
123+
No development has been done for this stage, but it will be quite similar
124+
to ``pre-scan``.
109125

110126
5. Other work:
111127
--------------
112128

113-
`Group cli options in cli help <https://github.com/nexB/scancode-toolkit/issues/709>`_
129+
`Group cli options in cli help
130+
<https://github.com/nexB/scancode-toolkit/issues/709>`_
114131

115-
Here, the goal was to add command line options to pre-defined groups such that they are displayed
116-
in their respective groups when ``scancode -h`` or ``scancode --help`` is called. This helped to
117-
better visually represent the command line options and determine more easily what context they
118-
belong to.
132+
Here, the goal was to add command line options to pre-defined groups such
133+
that they are displayed in their respective groups when ``scancode -h`` or
134+
``scancode --help`` is called. This helped to better visually represent the
135+
command line options and determine more easily what context they belong to.
119136

120-
`Add a Resource class to hold all scanned info <https://github.com/nexB/scancode-toolkit/issues/738>`_
121-
* ``Ongoing`` *
137+
`Add a Resource class to hold all scanned info
138+
<https://github.com/nexB/scancode-toolkit/issues/738>`_ * ``Ongoing`` *
122139

123-
Here, the goal was to create a ``Resource`` class, such that it holds all the scanned data for a
124-
resource (i.e a file or a directory). This class would go on to eventually encapsulate the caching
125-
logic entirely. For now, it just holds the ``info`` and ``path`` of a resource.
140+
Here, the goal was to create a ``Resource`` class, such that it holds all
141+
the scanned data for a resource (i.e a file or a directory). This class
142+
would go on to eventually encapsulate the caching logic entirely. For now,
143+
it just holds the ``info`` and ``path`` of a resource.
126144

127145
6. What's left?
128146
---------------
@@ -132,4 +150,5 @@ logic entirely. For now, it just holds the ``info`` and ``path`` of a resource.
132150
- More complex post-scan plugins
133151
- Support plugins written in languages other than python
134152

135-
**Additionally, all my commits can be found** `here <https://github.com/nexB/scancode-toolkit/commits/develop?author=yashdsaraf>`_.
153+
**Additionally, all my commits can be found** `here
154+
<https://github.com/nexB/scancode-toolkit/commits/develop?author=yashdsaraf>`_.

‎docs/source/archive/gsoc/reports/2019/deltacode_arnav.rst‎

Lines changed: 37 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -9,42 +9,47 @@ Project: Approximately similar file detection in DeltaCode
99
Project Overview
1010
----------------
1111

12-
DeltaCode is a tool to compare and report scan differences. It takes JSON files as an input which
13-
is the output of ScanCode-toolkit as well. When comparing files, it only uses the exact comparison.
14-
By exact comparison, I mean it compares the hash value of the files. The output of DeltaCode is a
15-
JSON/CSV file which includes the details of the scan such as delta score, delta count, etc. The
16-
goal of this project is to improve the usefulness of the delta by also finding files that are
17-
mostly the same (e.g. quasi or near duplicates) vs. files that are completely different. After this
18-
project, DeltaCode would be able to detect similar files in a directory approximately.
12+
DeltaCode is a tool to compare and report scan differences. It takes JSON
13+
files as an input which is the output of ScanCode-toolkit as well. When
14+
comparing files, it only uses the exact comparison. By exact comparison, I
15+
mean it compares the hash value of the files. The output of DeltaCode is a
16+
JSON/CSV file which includes the details of the scan such as delta score,
17+
delta count, etc. The goal of this project is to improve the usefulness of
18+
the delta by also finding files that are mostly the same (e.g. quasi or
19+
near duplicates) vs. files that are completely different. After this
20+
project, DeltaCode would be able to detect similar files in a directory
21+
approximately.
1922

2023
Requirements of the project
2124
---------------------------
2225

23-
- Provided two files using ScanCode-toolkit, the new near-duplicate detection should return the
24-
distance between the two files.
25-
- The code should be seamlessly integrated with ScanCode-toolkit. It should be highly configurable
26-
by the maintainers.
27-
- The strictness of near-duplicates should be noted and adjusted by a threshold variable.
26+
- Provided two files using ScanCode-toolkit, the new near-duplicate
27+
detection should return the distance between the two files.
28+
- The code should be seamlessly integrated with ScanCode-toolkit. It should
29+
be highly configurable by the maintainers.
30+
- The strictness of near-duplicates should be noted and adjusted by a
31+
threshold variable.
2832

2933
The Project
3034
-----------
3135

3236
- Addition of new fingerprint plugin in the ScanCode Toolkit.
33-
- Implementation and integration of the fingerprint generation algorithm in the ScanCode Toolkit
34-
codebase.
35-
- Implementation of distance finding algorithm between the files and process them further in the
36-
DeltaCode codebase.
37-
- Integration of fingerprint field in the JSON file to compare the deltas and provide them with
38-
appropriate scores.
39-
- Make changes to old unit tests and addition of new unit tests in ScanCode Toolkit as well as
40-
DeltaCode.
37+
- Implementation and integration of the fingerprint generation algorithm in
38+
the ScanCode Toolkit codebase.
39+
- Implementation of distance finding algorithm between the files and
40+
process them further in the DeltaCode codebase.
41+
- Integration of fingerprint field in the JSON file to compare the deltas
42+
and provide them with appropriate scores.
43+
- Make changes to old unit tests and addition of new unit tests in ScanCode
44+
Toolkit as well as DeltaCode.
4145

4246
I have completed all the tasks that were in the scope of this GSoC project.
4347

4448
Pull Requests
4549
-------------
4650

47-
- https://github.com/nexB/scancode-toolkit/pull/1576 [Closed] (something went wrong while rebasing)
51+
- https://github.com/nexB/scancode-toolkit/pull/1576 [Closed] (something
52+
went wrong while rebasing)
4853
- https://github.com/nexB/scancode-toolkit/pull/1651 [Merged]
4954
- https://github.com/nexB/deltacode/pull/128 [Merged]
5055

@@ -55,15 +60,19 @@ Links
5560
[Org Link] https://summerofcode.withgoogle.com/organizations/6118953540124672/
5661
[Project Link] https://summerofcode.withgoogle.com/projects/#6422961651712000
5762
58-
- `Project Details <https://summerofcode.withgoogle.com/organizations/6118953540124672/>`_
59-
- `Proposal <https://docs.google.com/document/d/1XGUH4Ogovc8ZTt_bjZc7ML75E1NrhTlAtelckESpSGA/edit?usp=sharing>`_
63+
- `Project Details
64+
<https://summerofcode.withgoogle.com/organizations/6118953540124672/>`_
65+
- `Proposal
66+
<https://docs.google.com/document/d/1XGUH4Ogovc8ZTt_bjZc7ML75E1NrhTlAtelckESpSGA/edit?usp=sharing>`_
6067
- `ScanCode Toolkit <https://github.com/nexB/scancode-toolkit>`_
6168
- `DeltaCode <https://github.com/nexB/deltacode>`_
6269

6370
------------
6471

65-
I’ve had a wonderful time during these three months and have learned plenty of things. I would
66-
really like to thank `@pombredanne <https://github.com/pombredanne>`_,
67-
`@steven-esser <https://github.com/steven-esser>`_, and `@JonoYang <https://github.com/JonoYang>`_ for their
68-
constant support throughout the journey. From good job claps to nit-picky constructive
69-
code-reviews, I enjoyed every bit of this GSoC project.
72+
I’ve had a wonderful time during these three months and have learned plenty
73+
of things. I would really like to thank `@pombredanne
74+
<https://github.com/pombredanne>`_, `@steven-esser
75+
<https://github.com/steven-esser>`_, and `@JonoYang
76+
<https://github.com/JonoYang>`_ for their constant support throughout the
77+
journey. From good job claps to nit-picky constructive code-reviews, I
78+
enjoyed every bit of this GSoC project.

0 commit comments

Comments
 (0)