aboutcode-org · satyajeetch1991 · Jul 23, 2025
diff --git a/.github/workflows/sync-readme-to-rst.yml b/.github/workflows/sync-readme-to-rst.yml
@@ -0,0 +1,37 @@
+name: Sync README.md to docs/index.rst
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'README.md'
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install m2r2 for Markdown → RST
+        run: |
+          pip install m2r2
+
+      - name: Convert README.md to docs/index.rst
+        run: |
+          m2r2 README.md --output docs/index.rst
+
+      - name: Commit and push changes (if any)
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git add docs/index.rst
+          git diff --cached --quiet || git commit -m "Sync README.md to docs/index.rst"
+          git push
diff --git a/README.md b/README.md
@@ -1,149 +1,110 @@
 # AboutCode
 
-### What is AboutCode?
+![Doc Build](https://github.com/aboutcode-org/aboutcode/actions/workflows/docs-ci.yml/badge.svg)
 
-AboutCode is a family of FOSS projects to uncover data ... about software:
+## What is AboutCode?
 
--   where does the code come from? which software package?
--   what is its license? copyright?
--   is the code vulnerable, maintained, well coded?
--   what are its dependencies, are there vulnerabilities/licensing issues?
+**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:
 
-All these are questions that are important to answer: there are millions of free
-and open source software components available on the web for reuse.
+- Where does this code come from?
+- What license or copyright does it carry?
+- Are there known vulnerabilities?
+- Who maintains it?
+- What are its dependencies?
 
-Knowing where a software package comes from, what its license is and whether it
-is vulnerable should be a problem of the past such that everyone can safely
-consume more free and open source software. We support not only open source
-software, but also open data, generated and curated by our applications.
+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.
 
-> [!NOTE]
-> This is a repository with information on aboutcode open source
-> activities and not the actual code repository. See the
-> [projects section](https://github.com/aboutcode-org/aboutcode#projects) below
-> for links to all the code repositories of our projects with a brief overview
-> and our [wiki](https://github.com/aboutcode-org/aboutcode/wiki) if you are
-> looking to participate.
+> **Note:**  
+> This is the meta-repository with information on AboutCode's open source activities, not the code itself.  
+> See the [Projects section](#projects) below or visit our [Wiki](https://github.com/aboutcode-org/aboutcode/wiki) for detailed links to the codebases.
 
-### Documentation Build
+---
+
+## 🔧 Documentation Build
+
+To manually build the documentation:
+
+```bash
+make docs
+
+## 🔗 Important Links
+
+- 🌐 **Website**: [aboutcode.org](https://aboutcode.org)
+- 📚 **Docs**: [aboutcode.readthedocs.io](https://aboutcode.readthedocs.io/en/latest/)
+- 💬 **Chat**:
+  - [Gitter: aboutcode-org#discuss](https://app.gitter.im/#/room/#aboutcode-org_discuss:gitter.im)
+  - [Element (Matrix)](https://matrix.to/#/#aboutcode-org_discuss:gitter.im) — use `gitter.im` as the homeserver
+- 📅 **Weekly Meetings**: [Meeting Minutes](https://github.com/aboutcode-org/aboutcode/wiki/MeetingMinutes)
+- 📖 **GSoC Info**: [GSoC Wiki](https://github.com/aboutcode-org/aboutcode/wiki)
+
+---
+
+## 🚀 Projects
+
+Each AboutCode project has its own repository and purpose. Here are the key ones:
+
+### 🧩 Core Projects
+
+- **[ScanCode Toolkit](https://github.com/aboutcode-org/scancode-toolkit)**  
+  Detect origin, license, and dependencies in source code. Most popular tool.
+
+- **[Scancode.io](https://github.com/aboutcode-org/scancode.io)**  
+  Web-based and API-driven UI for running ScanCode in pipelines on containers and packages.
+
+- **[VulnerableCode](https://github.com/aboutcode-org/vulnerablecode)**  
+  API and DB to track vulnerabilities in software packages. Includes Vulntotal tool.
+
+- **[purlDB](https://github.com/aboutcode-org/purldb)**  
+  Database of package URLs (purls) and associated data from scans.
+
+- **[FetchCode](https://github.com/aboutcode-org/fetchcode)**  
+  Library for fetching code via HTTP, FTP, Git, etc.
+
+- **[AboutCode Toolkit](https://github.com/aboutcode-org/aboutcode-toolkit)**  
+  CLI tools to document code provenance and generate attribution notices using YAML.
+
+- **[container-inspector](https://github.com/aboutcode-org/container-inspector)**  
+  Analyze Docker images for component structure and origin.
+
+- **[Scancode Workbench](https://github.com/aboutcode-org/scancode-workbench)**  
+  GUI app to visualize and review ScanCode results (React-based).
+
+---
+
+### 🛠️ Support Tools
+
+- **[univers](https://github.com/aboutcode-org/univers)**  
+  Parse and compare package versions and version ranges.
+
+- **[python-inspector](https://github.com/aboutcode-org/python-inspector)**  
+  Inspect Python packages and dependencies.
+
+- **[nuget-inspector](https://github.com/aboutcode-org/nuget-inspector)**  
+  Same as above, for NuGet (C#/.NET) packages.
+
+- **[license-expression](https://github.com/aboutcode-org/license-expression)**  
+  Normalize and compare SPDX-like license expressions with boolean logic.
+
+- **[TraceCode Toolkit](https://github.com/aboutcode-org/tracecode-toolkit)**  
+  Use `strace` to map binary files back to source via syscall tracing.
+
+---
+
+### 🌐 Standards and Community Work
+
+We actively collaborate with and contribute to:
+
+- [Package URL (purl)](https://github.com/package-url) — Standard to identify software packages
+- [SPDX](https://spdx.org) — Open standard for software licensing metadata
+- [CycloneDX](https://cyclonedx.org) — OWASP BOM spec for supply chain risk
+- [ClearlyDefined](https://clearlydefined.io) — Improve open source licensing metadata
+
+---
+
+### 🧬 Data Model
+
+- **ABCD (AboutCode Data)**  
+  Shared data format for interoperability across AboutCode tools.  
+  See [AboutCode Data Docs](https://aboutcode.readthedocs.io/en/latest/aboutcode-data/abcd.html).
 
-![Doc Build](https://github.com/aboutcode-org/aboutcode/actions/workflows/docs-ci.yml/badge.svg)
 
-> [!NOTE]
-> To manually build the documentation, run the `$ make docs` command from 
-> the root of this repo.
-
-### Important Links
-
-Our homepage is at http://aboutcode.org
-
-Our documentation (in progress) is at
-https://aboutcode.readthedocs.io/en/latest/
-
-Join the chat online at
-[app.gitter.im : aboutcode-org#discuss](https://app.gitter.im/#/room/#aboutcode-org_discuss:gitter.im)
-or if you're using the element app set the homeserver to `gitter.im` and then
-join the
-[aboutcode-org#discuss](https://matrix.to/#/#aboutcode-org_discuss:gitter.im)
-chatroom. Introduce yourself and start the discussion!
-
-Look at our [wiki](https://github.com/aboutcode-org/aboutcode/wiki) for
-information about our participation in the GSoC program.
-
-We have a weekly meeting, see more details
-[here](https://github.com/aboutcode-org/aboutcode/wiki/MeetingMinutes).
-
-### Projects
-
-Each AboutCode project has its own repository:
-
--   **[ScanCode Toolkit](https://github.com/aboutcode-org/scancode-toolkit)**: a
-    set of code scanning tools to detect the origin and license of code and
-    dependencies. ScanCode now uses a plug-in architecture to run a series of
-    scan-related tools in one process flow. This is the most popular project and
-    is used by 100's of software teams . The lead maintainer is @pombredanne
-
--   **[Scancode.io](https://github.com/aboutcode-org/scancode.io)**: is a
-    web-based and API to run and review scans in rich scripted pipelines, on
-    different kinds of containers, docker images, package archives, manifests
-    etc, to get information on licenses, copyrights, source, vulneribilities.
-    The lead maintainer is @tdruez
-
--   **[VulnerableCode](https://github.com/aboutcode-org/vulnerablecode)**: is a
-    web-based API and database to collect and track all the known software
-    package vulnerabilities, with affected and fixed packages, references and a
-    standalone tool Vulntotal to compare this vulneribility information across
-    similar tools. This is maintained by @tg1999 and @pombredanne
-
--   **[univers](https://github.com/aboutcode-org/univers)** is a package to
-    parse and compare all the package versions and all the ranges.
-
--   **[purlDB](https://github.com/aboutcode-org/purldb)** consists of tools to
-    create and expose a database of purls (Package URLs) and also has package
-    data for all of these packages created from scans. This is maintained by
-    @jyang
-
--   **[FetchCode](https://github.com/aboutcode-org/fetchcode)** is a library to
-    reliably fetch any code via HTTP, FTP and version control systems such as
-    git.
-
--   **[Scancode Workbench](https://github.com/aboutcode-org/scancode-workbench)**:
-    a desktop application based on typescript and react to visualize and review
-    scan results from scancode scans.
-
--   **[AboutCode Toolkit](https://github.com/aboutcode-org/aboutcode-toolkit)**:
-    a set of command line tools to document the provenance of your code and
-    generate attribution notices. AboutCode Toolkit uses small yaml files to
-    document code provenance inside a codebase. The lead maintainer is
-    @chinyeungli
-
--   **[container-inspector](https://github.com/aboutcode-org/container-inspector)**:
-    a tool to analyze the structure and provenance of software components in
-    Docker images using static analysis. Maintained by @pombredanne
-
--   **[python-inspector](https://github.com/aboutcode-org/python-inspector)**
-    and **[nuget inspector](https://github.com/aboutcode-org/nuget-inspector/)**
-    inspects manifests and code to resolve dependencies (vulnerable and
-    non-vulnerable) for python and nuget packages respectively.
-
--   **[license-expression](https://github.com/aboutcode-org/license-expression/)**:
-    a library to parse, analyze, compare and normalize SPDX and SPDX-like
-    license expressions using a boolean logic expression engine. See
-    https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 to
-    understand what an expression is. See
-    https://github.com/aboutcode-org/license-expression for the code. The
-    underlying boolean engine is live at https://github.com/bastikr/boolean.py .
-    Both are co-maintained by @pombredanne
-
--   **ABCD aka AboutCode Data**: a simple set of conventions to define data
-    structures that all the AboutCode tools can understand and use to exchange
-    data. The details are at
-    [AboutCode Data](https://aboutcode.readthedocs.io/en/latest/aboutcode-data/abcd.html).
-    ABOUT files and ScanCode Toolkit data are examples of this approach. Other
-    projects such as https://libraries.io and and
-    [OSS Review Toolkit](https://github.com/heremaps/oss-review-toolkit) are
-    also using these conventions.
-
--   **[TraceCode Toolkit](https://github.com/aboutcode-org/tracecode-toolkit)**:
-    a set of tools to trace files from your deployment or distribution packages
-    back to their origin in a development codebase or repository. The primary
-    tool uses strace https://github.com/strace/strace/ to trace system calls on
-    Linux and construct a build graph from syscalls to show which files are used
-    to build a binary. We are contributors to strace. Maintained by @pombredanne
-
-We also co-started and worked closely with other FOSS orgs and projects:
-
--   [Package URL](https://github.com/package-url): a widely used standard to
-    reference software packages of all types with simple, readable and concise
-    URLs.
-
--   [SPDX](http://SPDX.org): aka. Software Package Data Exchange, a spec to
-    document the origin and licensing of packages.
-
--   [CycloneDX](https://cyclonedx.org) aka. OWASP CycloneDX is a full-stack Bill
-    of Materials (BOM) standard that provides advanced supply chain capabilities
-    for cyber risk reduction
-
--   [ClearlyDefined](https://ClearlyDefined.io): a project to review and help
-    FOSS projects improve their licensing and documentation clarity. This
-    project is incubating with https://opensource.org
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,20 +1,14 @@
-#########
-AboutCode
-#########
+####################
+AboutCode Documentation
+####################
 
-Welcome to the AboutCode documentation homepage. `AboutCode.org
-<https://www.aboutcode.org/>`_ is a community of open source developers who
-are trying to make open source easier to use by providing open source tools
-to discover, identify and track open source components (aka Software
-Composition Analysis – SCA). AboutCode is the collective name for these
-open source tools.
+Welcome to the AboutCode documentation homepage!
 
-This home page provides a directory of our major projects and their
-documentation on ReadTheDocs plus information about how to contribute to
-AboutCode documentation.
+`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**).
 
-All community contributions are welcome.
+These tools support license compliance, vulnerability tracking, attribution generation, and metadata normalization.
 
+All community contributions are welcome 🚀
 
 ----
 
@@ -23,26 +17,77 @@ Overview
 ********
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    aboutcode-project-overview
 
+********
+Projects
+********
+
+AboutCode includes core tools, support utilities, and standard formats. Here are the highlights:
+
+🧩 Core Projects
+================
+
+- **ScanCode Toolkit** — Detect origin, license, and dependencies in source code
+- **Scancode.io** — Web/API UI for running ScanCode pipelines
+- **VulnerableCode** — Track software package vulnerabilities
+- **purlDB** — Database of Package URLs (purls) with scan data
+- **AboutCode Toolkit** — Generate attribution documentation from scans
+- **container-inspector** — Inspect Docker image layers and component origins
+
+🛠️ Support Tools
+=================
+
+- **univers** — Compare and normalize package versions and ranges
+- **python-inspector** — Analyze Python packages and dependencies
+- **nuget-inspector** — Inspector for NuGet (.NET) packages
+- **license-expression** — Normalize/compare SPDX-like license expressions
+- **TraceCode Toolkit** — Use `strace` to trace binaries back to source
+
+📘 Shared Data: ABCD
+=====================
+
+- **AboutCode Data (ABCD)** — Interoperable JSON/YAML data format for all tools  
+  See: :doc:`aboutcode-data/abcd`
+
+----
+
 ************
 Contributing
 ************
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    contributing
 
+We welcome all contributions: bug fixes, docs, new features, or ideas!  
+💬 Join the discussion on Gitter or Matrix.  
+🧪 Try the tools and report issues.  
+📘 See the contributing guide for more.
+
+----
+
 ******
 Others
 ******
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   aboutcode-data/abcd
    archive
    license
+
+----
+
+***************
+🔗 Important Links
+***************
+
+- 🌐 Website: https://aboutcode.org
+- 📚 Docs: https://aboutcode.readthedocs.io
+- 💬 Chat: [Gitter](https://gitter.im/aboutcode-org/discuss) or Element (Matrix)
+- 🗓️ Meetings: `Meeting Minutes <https://github.com/nexB/aboutcode/wiki/Meeting-Notes>`_
+- 📖 GSoC Info: `GSoC Wiki <https://github.com/nexB/aboutcode/wiki/GSoC>`_