diff --git a/.github/workflows/sync-readme-to-rst.yml b/.github/workflows/sync-readme-to-rst.yml new file mode 100644 index 0000000..d94f1a7 --- /dev/null +++ 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 index 0e73029..2b76cc0 100644 --- 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 index e13bf63..7510c0a 100644 --- 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 -`_ 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 `_ 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 `_ +- ๐Ÿ“– GSoC Info: `GSoC Wiki `_