Skip to content

Commit db6db91

Browse files
satyajeetch1991satyajeetch1991
committed
docs(#198): sync README and RTD index content
- Updated 'What is AboutCode?' and 'Projects' sections in README.md - Reflected the same updates in docs/index.rst to ensure consistency - Added GitHub Action to auto-sync README to RTD using rst format - Fulfills the proposal in issue #198 for improving AboutCode TOC documentation
1 parent 0ca1881 commit db6db91

File tree

3 files changed

+199
-156
lines changed

3 files changed

+199
-156
lines changed

‎.github/workflows/sync-readme-to-rst.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Sync README.md to docs/index.rst
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'README.md'
8+
workflow_dispatch:
9+
10+
jobs:
11+
sync:
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- name: Checkout repository
16+
uses: actions/checkout@v3
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v4
20+
with:
21+
python-version: '3.11'
22+
23+
- name: Install m2r2 for Markdown → RST
24+
run: |
25+
pip install m2r2
26+
27+
- name: Convert README.md to docs/index.rst
28+
run: |
29+
m2r2 README.md --output docs/index.rst
30+
31+
- name: Commit and push changes (if any)
32+
run: |
33+
git config --global user.name 'github-actions[bot]'
34+
git config --global user.email 'github-actions[bot]@users.noreply.github.com'
35+
git add docs/index.rst
36+
git diff --cached --quiet || git commit -m "Sync README.md to docs/index.rst"
37+
git push

‎README.md‎

Lines changed: 100 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,110 @@
11
# AboutCode
22

3-
### What is AboutCode?
3+
![Doc Build](https://github.com/aboutcode-org/aboutcode/actions/workflows/docs-ci.yml/badge.svg)
44

5-
AboutCode is a family of FOSS projects to uncover data ... about software:
5+
## What is AboutCode?
66

7-
- where does the code come from? which software package?
8-
- what is its license? copyright?
9-
- is the code vulnerable, maintained, well coded?
10-
- what are its dependencies, are there vulnerabilities/licensing issues?
7+
**AboutCode** is a collection of FOSS (Free and Open Source Software) projects focused on Software Composition Analysis (SCA). It helps you answer critical questions about software:
118

12-
All these are questions that are important to answer: there are millions of free
13-
and open source software components available on the web for reuse.
9+
- Where does this code come from?
10+
- What license or copyright does it carry?
11+
- Are there known vulnerabilities?
12+
- Who maintains it?
13+
- What are its dependencies?
1414

15-
Knowing where a software package comes from, what its license is and whether it
16-
is vulnerable should be a problem of the past such that everyone can safely
17-
consume more free and open source software. We support not only open source
18-
software, but also open data, generated and curated by our applications.
15+
In today's world of millions of open source components, it's essential to understand code origin, licensing, and security risks before reuse. AboutCode tools are designed to make this easy and reliable.
1916

20-
> [!NOTE]
21-
> This is a repository with information on aboutcode open source
22-
> activities and not the actual code repository. See the
23-
> [projects section](https://github.com/aboutcode-org/aboutcode#projects) below
24-
> for links to all the code repositories of our projects with a brief overview
25-
> and our [wiki](https://github.com/aboutcode-org/aboutcode/wiki) if you are
26-
> looking to participate.
17+
> **Note:**
18+
> This is the meta-repository with information on AboutCode's open source activities, not the code itself.
19+
> See the [Projects section](#projects) below or visit our [Wiki](https://github.com/aboutcode-org/aboutcode/wiki) for detailed links to the codebases.
2720
28-
### Documentation Build
21+
---
22+
23+
## 🔧 Documentation Build
24+
25+
To manually build the documentation:
26+
27+
```bash
28+
make docs
29+
30+
## 🔗 Important Links
31+
32+
- 🌐 **Website**: [aboutcode.org](https://aboutcode.org)
33+
- 📚 **Docs**: [aboutcode.readthedocs.io](https://aboutcode.readthedocs.io/en/latest/)
34+
- 💬 **Chat**:
35+
- [Gitter: aboutcode-org#discuss](https://app.gitter.im/#/room/#aboutcode-org_discuss:gitter.im)
36+
- [Element (Matrix)](https://matrix.to/#/#aboutcode-org_discuss:gitter.im) — use `gitter.im` as the homeserver
37+
- 📅 **Weekly Meetings**: [Meeting Minutes](https://github.com/aboutcode-org/aboutcode/wiki/MeetingMinutes)
38+
- 📖 **GSoC Info**: [GSoC Wiki](https://github.com/aboutcode-org/aboutcode/wiki)
39+
40+
---
41+
42+
## 🚀 Projects
43+
44+
Each AboutCode project has its own repository and purpose. Here are the key ones:
45+
46+
### 🧩 Core Projects
47+
48+
- **[ScanCode Toolkit](https://github.com/aboutcode-org/scancode-toolkit)**
49+
Detect origin, license, and dependencies in source code. Most popular tool.
50+
51+
- **[Scancode.io](https://github.com/aboutcode-org/scancode.io)**
52+
Web-based and API-driven UI for running ScanCode in pipelines on containers and packages.
53+
54+
- **[VulnerableCode](https://github.com/aboutcode-org/vulnerablecode)**
55+
API and DB to track vulnerabilities in software packages. Includes Vulntotal tool.
56+
57+
- **[purlDB](https://github.com/aboutcode-org/purldb)**
58+
Database of package URLs (purls) and associated data from scans.
59+
60+
- **[FetchCode](https://github.com/aboutcode-org/fetchcode)**
61+
Library for fetching code via HTTP, FTP, Git, etc.
62+
63+
- **[AboutCode Toolkit](https://github.com/aboutcode-org/aboutcode-toolkit)**
64+
CLI tools to document code provenance and generate attribution notices using YAML.
65+
66+
- **[container-inspector](https://github.com/aboutcode-org/container-inspector)**
67+
Analyze Docker images for component structure and origin.
68+
69+
- **[Scancode Workbench](https://github.com/aboutcode-org/scancode-workbench)**
70+
GUI app to visualize and review ScanCode results (React-based).
71+
72+
---
73+
74+
### 🛠️ Support Tools
75+
76+
- **[univers](https://github.com/aboutcode-org/univers)**
77+
Parse and compare package versions and version ranges.
78+
79+
- **[python-inspector](https://github.com/aboutcode-org/python-inspector)**
80+
Inspect Python packages and dependencies.
81+
82+
- **[nuget-inspector](https://github.com/aboutcode-org/nuget-inspector)**
83+
Same as above, for NuGet (C#/.NET) packages.
84+
85+
- **[license-expression](https://github.com/aboutcode-org/license-expression)**
86+
Normalize and compare SPDX-like license expressions with boolean logic.
87+
88+
- **[TraceCode Toolkit](https://github.com/aboutcode-org/tracecode-toolkit)**
89+
Use `strace` to map binary files back to source via syscall tracing.
90+
91+
---
92+
93+
### 🌐 Standards and Community Work
94+
95+
We actively collaborate with and contribute to:
96+
97+
- [Package URL (purl)](https://github.com/package-url) — Standard to identify software packages
98+
- [SPDX](https://spdx.org) — Open standard for software licensing metadata
99+
- [CycloneDX](https://cyclonedx.org) — OWASP BOM spec for supply chain risk
100+
- [ClearlyDefined](https://clearlydefined.io) — Improve open source licensing metadata
101+
102+
---
103+
104+
### 🧬 Data Model
105+
106+
- **ABCD (AboutCode Data)**
107+
Shared data format for interoperability across AboutCode tools.
108+
See [AboutCode Data Docs](https://aboutcode.readthedocs.io/en/latest/aboutcode-data/abcd.html).
29109

30-
![Doc Build](https://github.com/aboutcode-org/aboutcode/actions/workflows/docs-ci.yml/badge.svg)
31110

32-
> [!NOTE]
33-
> To manually build the documentation, run the `$ make docs` command from
34-
> the root of this repo.
35-
36-
### Important Links
37-
38-
Our homepage is at http://aboutcode.org
39-
40-
Our documentation (in progress) is at
41-
https://aboutcode.readthedocs.io/en/latest/
42-
43-
Join the chat online at
44-
[app.gitter.im : aboutcode-org#discuss](https://app.gitter.im/#/room/#aboutcode-org_discuss:gitter.im)
45-
or if you're using the element app set the homeserver to `gitter.im` and then
46-
join the
47-
[aboutcode-org#discuss](https://matrix.to/#/#aboutcode-org_discuss:gitter.im)
48-
chatroom. Introduce yourself and start the discussion!
49-
50-
Look at our [wiki](https://github.com/aboutcode-org/aboutcode/wiki) for
51-
information about our participation in the GSoC program.
52-
53-
We have a weekly meeting, see more details
54-
[here](https://github.com/aboutcode-org/aboutcode/wiki/MeetingMinutes).
55-
56-
### Projects
57-
58-
Each AboutCode project has its own repository:
59-
60-
- **[ScanCode Toolkit](https://github.com/aboutcode-org/scancode-toolkit)**: a
61-
set of code scanning tools to detect the origin and license of code and
62-
dependencies. ScanCode now uses a plug-in architecture to run a series of
63-
scan-related tools in one process flow. This is the most popular project and
64-
is used by 100's of software teams . The lead maintainer is @pombredanne
65-
66-
- **[Scancode.io](https://github.com/aboutcode-org/scancode.io)**: is a
67-
web-based and API to run and review scans in rich scripted pipelines, on
68-
different kinds of containers, docker images, package archives, manifests
69-
etc, to get information on licenses, copyrights, source, vulneribilities.
70-
The lead maintainer is @tdruez
71-
72-
- **[VulnerableCode](https://github.com/aboutcode-org/vulnerablecode)**: is a
73-
web-based API and database to collect and track all the known software
74-
package vulnerabilities, with affected and fixed packages, references and a
75-
standalone tool Vulntotal to compare this vulneribility information across
76-
similar tools. This is maintained by @tg1999 and @pombredanne
77-
78-
- **[univers](https://github.com/aboutcode-org/univers)** is a package to
79-
parse and compare all the package versions and all the ranges.
80-
81-
- **[purlDB](https://github.com/aboutcode-org/purldb)** consists of tools to
82-
create and expose a database of purls (Package URLs) and also has package
83-
data for all of these packages created from scans. This is maintained by
84-
@jyang
85-
86-
- **[FetchCode](https://github.com/aboutcode-org/fetchcode)** is a library to
87-
reliably fetch any code via HTTP, FTP and version control systems such as
88-
git.
89-
90-
- **[Scancode Workbench](https://github.com/aboutcode-org/scancode-workbench)**:
91-
a desktop application based on typescript and react to visualize and review
92-
scan results from scancode scans.
93-
94-
- **[AboutCode Toolkit](https://github.com/aboutcode-org/aboutcode-toolkit)**:
95-
a set of command line tools to document the provenance of your code and
96-
generate attribution notices. AboutCode Toolkit uses small yaml files to
97-
document code provenance inside a codebase. The lead maintainer is
98-
@chinyeungli
99-
100-
- **[container-inspector](https://github.com/aboutcode-org/container-inspector)**:
101-
a tool to analyze the structure and provenance of software components in
102-
Docker images using static analysis. Maintained by @pombredanne
103-
104-
- **[python-inspector](https://github.com/aboutcode-org/python-inspector)**
105-
and **[nuget inspector](https://github.com/aboutcode-org/nuget-inspector/)**
106-
inspects manifests and code to resolve dependencies (vulnerable and
107-
non-vulnerable) for python and nuget packages respectively.
108-
109-
- **[license-expression](https://github.com/aboutcode-org/license-expression/)**:
110-
a library to parse, analyze, compare and normalize SPDX and SPDX-like
111-
license expressions using a boolean logic expression engine. See
112-
https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 to
113-
understand what an expression is. See
114-
https://github.com/aboutcode-org/license-expression for the code. The
115-
underlying boolean engine is live at https://github.com/bastikr/boolean.py .
116-
Both are co-maintained by @pombredanne
117-
118-
- **ABCD aka AboutCode Data**: a simple set of conventions to define data
119-
structures that all the AboutCode tools can understand and use to exchange
120-
data. The details are at
121-
[AboutCode Data](https://aboutcode.readthedocs.io/en/latest/aboutcode-data/abcd.html).
122-
ABOUT files and ScanCode Toolkit data are examples of this approach. Other
123-
projects such as https://libraries.io and and
124-
[OSS Review Toolkit](https://github.com/heremaps/oss-review-toolkit) are
125-
also using these conventions.
126-
127-
- **[TraceCode Toolkit](https://github.com/aboutcode-org/tracecode-toolkit)**:
128-
a set of tools to trace files from your deployment or distribution packages
129-
back to their origin in a development codebase or repository. The primary
130-
tool uses strace https://github.com/strace/strace/ to trace system calls on
131-
Linux and construct a build graph from syscalls to show which files are used
132-
to build a binary. We are contributors to strace. Maintained by @pombredanne
133-
134-
We also co-started and worked closely with other FOSS orgs and projects:
135-
136-
- [Package URL](https://github.com/package-url): a widely used standard to
137-
reference software packages of all types with simple, readable and concise
138-
URLs.
139-
140-
- [SPDX](http://SPDX.org): aka. Software Package Data Exchange, a spec to
141-
document the origin and licensing of packages.
142-
143-
- [CycloneDX](https://cyclonedx.org) aka. OWASP CycloneDX is a full-stack Bill
144-
of Materials (BOM) standard that provides advanced supply chain capabilities
145-
for cyber risk reduction
146-
147-
- [ClearlyDefined](https://ClearlyDefined.io): a project to review and help
148-
FOSS projects improve their licensing and documentation clarity. This
149-
project is incubating with https://opensource.org

‎docs/source/index.rst‎

Lines changed: 62 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,14 @@
1-
#########
2-
AboutCode
3-
#########
1+
####################
2+
AboutCode Documentation
3+
####################
44

5-
Welcome to the AboutCode documentation homepage. `AboutCode.org
6-
<https://www.aboutcode.org/>`_ is a community of open source developers who
7-
are trying to make open source easier to use by providing open source tools
8-
to discover, identify and track open source components (aka Software
9-
Composition Analysis – SCA). AboutCode is the collective name for these
10-
open source tools.
5+
Welcome to the AboutCode documentation homepage!
116

12-
This home page provides a directory of our major projects and their
13-
documentation on ReadTheDocs plus information about how to contribute to
14-
AboutCode documentation.
7+
`AboutCode.org <https://www.aboutcode.org/>`_ is a community of open source developers helping make open source easier to use. We build **open source tools** to **discover**, **identify**, and **track** open source components (a process often called **Software Composition Analysis – SCA**).
158

16-
All community contributions are welcome.
9+
These tools support license compliance, vulnerability tracking, attribution generation, and metadata normalization.
1710

11+
All community contributions are welcome 🚀
1812

1913
----
2014

@@ -23,26 +17,77 @@ Overview
2317
********
2418

2519
.. toctree::
26-
:maxdepth: 3
20+
:maxdepth: 2
2721

2822
aboutcode-project-overview
2923

24+
********
25+
Projects
26+
********
27+
28+
AboutCode includes core tools, support utilities, and standard formats. Here are the highlights:
29+
30+
🧩 Core Projects
31+
================
32+
33+
- **ScanCode Toolkit** — Detect origin, license, and dependencies in source code
34+
- **Scancode.io** — Web/API UI for running ScanCode pipelines
35+
- **VulnerableCode** — Track software package vulnerabilities
36+
- **purlDB** — Database of Package URLs (purls) with scan data
37+
- **AboutCode Toolkit** — Generate attribution documentation from scans
38+
- **container-inspector** — Inspect Docker image layers and component origins
39+
40+
🛠️ Support Tools
41+
=================
42+
43+
- **univers** — Compare and normalize package versions and ranges
44+
- **python-inspector** — Analyze Python packages and dependencies
45+
- **nuget-inspector** — Inspector for NuGet (.NET) packages
46+
- **license-expression** — Normalize/compare SPDX-like license expressions
47+
- **TraceCode Toolkit** — Use `strace` to trace binaries back to source
48+
49+
📘 Shared Data: ABCD
50+
=====================
51+
52+
- **AboutCode Data (ABCD)** — Interoperable JSON/YAML data format for all tools
53+
See: :doc:`aboutcode-data/abcd`
54+
55+
----
56+
3057
************
3158
Contributing
3259
************
3360

3461
.. toctree::
35-
:maxdepth: 3
62+
:maxdepth: 2
3663

3764
contributing
3865

66+
We welcome all contributions: bug fixes, docs, new features, or ideas!
67+
💬 Join the discussion on Gitter or Matrix.
68+
🧪 Try the tools and report issues.
69+
📘 See the contributing guide for more.
70+
71+
----
72+
3973
******
4074
Others
4175
******
4276

4377
.. toctree::
44-
:maxdepth: 2
78+
:maxdepth: 1
4579

46-
aboutcode-data/abcd
4780
archive
4881
license
82+
83+
----
84+
85+
***************
86+
🔗 Important Links
87+
***************
88+
89+
- 🌐 Website: https://aboutcode.org
90+
- 📚 Docs: https://aboutcode.readthedocs.io
91+
- 💬 Chat: [Gitter](https://gitter.im/aboutcode-org/discuss) or Element (Matrix)
92+
- 🗓️ Meetings: `Meeting Minutes <https://github.com/nexB/aboutcode/wiki/Meeting-Notes>`_
93+
- 📖 GSoC Info: `GSoC Wiki <https://github.com/nexB/aboutcode/wiki/GSoC>`_

0 commit comments

Comments
 (0)