Docs : Content Organization and Documentation Updates

CHANGELOG.md

@@ -1,4 +1,20 @@
-# Changelog 
+<!--!
+\page changelog Releases                                                               
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [Releases](https://p4lang.github.io/p4c/changelog.html)
+-->
+<!--!
+\internal
+-->
+# Releases
+<!--!
+\endinternal
+-->
+
 ## Semantic Versioning
 We follow a monthly release cadence. Our versioning scheme is as follows:
 - **Major.Minor.Patch** versions align with the P4 specification.

CONTRIBUTING.md

@@ -1,5 +1,22 @@
+<!--!
+\page contribute Contribute to the P4 Compiler Project                                                                      
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [Contribute to the P4 Compiler Project](https://p4lang.github.io/p4c/contribute.html)
+-->
+<!--!
+\internal
+-->
 # Contribute to the P4 Compiler Project
-
+<!--!
+\endinternal
+-->
+<!--!
+[TOC]
+-->
 Thank you for considering contributing to the P4 Compiler Project (P4C)! Your contributions are valuable and help improve the project for everyone. Before getting started, please take a moment to review the following guidelines.
 
 ## Contributing License
@@ -37,3 +54,7 @@ If you encounter any issues or have suggestions for improvement, please [open an
 We welcome feature requests! Please open an issue and provide as much detail as possible about the requested feature and its use case.
 
 Happy coding!
+
+<!--! 
+\include{doc} "../docs/CodingStandardPhilosophy.md" 
+-->

README.md

@@ -1,11 +1,27 @@
+<!--!
+\page getting_started Getting Started                                    
+-->
+<!--!
+\internal
+-->
 # P4C
+<!--!
+\endinternal
+-->
+<!--!
+[TOC]
+-->
 [![Main Build](https://github.com/p4lang/p4c/actions/workflows/ci-test-debian.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-test-debian.yml)
 [![Main Build](https://github.com/p4lang/p4c/actions/workflows/ci-test-fedora.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-test-fedora.yml)
 [![Main Build](https://github.com/p4lang/p4c/actions/workflows/ci-test-mac.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-test-mac.yml)
 [![Bazel Build](https://github.com/p4lang/p4c/actions/workflows/ci-bazel.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-bazel.yml)
 [![Validation](https://github.com/p4lang/p4c/actions/workflows/ci-validation-nightly.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-validation-nightly.yml)
 [![Docker Container](https://github.com/p4lang/p4c/actions/workflows/ci-container-image.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-container-image.yml)
 
+<!--!
+\internal
+-->
+* [Sample Backends in P4C](#sample-backends-in-p4c)
 * [Getting started](#getting-started)
    * [Installing packaged versions of P4C](#installing-packaged-versions-of-p4c)
    * [Installing P4C from source](#installing-p4c-from-source)
@@ -27,7 +43,9 @@
 * [How to Contribute](#how-to-contribute)
 * [P4 Compiler Onboarding](#p4-compiler-onboarding)
 * [Contact](#contact)
-
+<!--!
+\endinternal
+-->
 P4C is a reference compiler for the P4 programming language.
 It supports both P4-14 and P4-16; you can find more information about P4
 [here](http://p4.org) and the specifications for both versions of the language
@@ -41,7 +59,11 @@ P4C is modular; it provides a standard frontend and midend which can be combined
 with a target-specific backend to create a complete P4 compiler. The goal is to
 make adding new backends easy.
 
-The code contains seven sample backends:
+<!--!
+\include{doc} "../docs/doxygen/01_overview.md"
+-->
+## Sample Backends in P4C
+P4C includes seven sample backends, catering to different target architectures and use cases:
 * p4c-bm2-ss: can be used to target the P4 `simple_switch` written using
   the [BMv2 behavioral model](https://github.com/p4lang/behavioral-model),
 * p4c-dpdk: can be used to target the [DPDK software switch (SWX) pipeline](https://doc.dpdk.org/guides/rel_notes/release_20_11.html),
@@ -652,6 +674,9 @@ install (FILES ${CMAKE_CURRENT_SOURCE_DIR}/driver/p4c.mybackend.cfg
   DESTINATION ${P4C_ARTIFACTS_OUTPUT_DIRECTORY}/p4c_src)
 ```
 
+<!--!
+\include{doc} "../lib/README.md"
+-->
 ## Known issues
 
 Issues with the compiler are tracked on

backends/bmv2/README.md

@@ -1,5 +1,23 @@
+<!--!
+\page behavioral_model_backend Behavioral Model Backend                                                                       
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: https://p4lang.github.io/p4c/behavioral_model_backend.html
+-->
+<!--!
+\internal
+-->
 # Behavioral Model Backend
+<!--!
+\endinternal
+-->
 
+<!--!
+[TOC]
+-->
 This is a back-end which generates code for the [Behavioral Model version 2 (BMv2)](https://github.com/p4lang/behavioral-model.git).
 
 It can accept either P4_14 programs, or P4_16 programs written for the
@@ -41,3 +59,11 @@ controlc c() {
 - user-defined extern types / methods which are not defined in `v1model.p4`
 
 - stacks of header unions
+
+<!--!
+\include{doc} "../backends/bmv2/pna_nic/README.md" 
+-->
+
+<!--!
+\include{doc} "../backends/bmv2/portable_common/README.md" 
+-->

backends/bmv2/pna_nic/README.md

@@ -1,29 +1,21 @@
-# BMv2 "pna_nic" Backend
-
-This directory contains components specific to the BMv2's PNA NIC (Portable NIC Architecture) backend in the P4C compiler. The files in this folder depend on each other, on the files in the `bmv2/common` and  `portable_common` directories. Most of the classes are inherited from the classes in the `portable_common` directory.
-
-Output Binary: `p4c-bm2-pna`
-
-#### pnaProgramStructure.h, pnaProgramStructure.cpp
-
-Defines and implements the program structure (metadata, parsers, controls, and deparsers) and parsing logic specific to the BMv2's PNA NIC backend.
-
-##### midend.h, midend.cpp
+<!-- 
+Documentation Inclusion:
+This README is integrated as a subsection of the "Behavioral Model Backend" page in the P4 compiler documentation.
 
-Defines the mid-end processing of the PNA NIC compiler. Performs various transformations and optimizations on the program's Intermediate Representation (IR).
+Refer to the specific section here: [BMv2 "pna_nic" Backend - Subsection](https://p4lang.github.io/p4c/behavioral_model_backend.html#bmv2-pna_nic-backend)
+-->
 
-##### options.h, options.cpp
-
-Manages the command-line options for the PNA NIC compiler.
-
-##### pnaNic.h, pnaNic.cpp
-
-Provides backend implementation to the BMv2's PNA NIC compiler.
-
-##### main.cpp
+# BMv2 "pna_nic" Backend
 
-Sets up compilation environment, integrates various components, and executes the PNA NIC compiler.
+The [`backends/bmv2/pna_nic` directory](https://github.com/p4lang/p4c/tree/main/backends/bmv2/pna_nic) contains components specific to the BMv2's PNA NIC (Portable NIC Architecture) backend in the P4C compiler. The files in this folder depend on each other, on the files in the `bmv2/common` and  `portable_common` directories. Most of the classes are inherited from the classes in the `portable_common` directory.
 
-##### version.h.cmake
+Output Binary: `p4c-bm2-pna`
 
-Defines macros containing version information for the PNA NIC compiler.
+| File(s)                      | Description |
+|------------------------------|-------------|
+| `pnaProgramStructure.h`, `pnaProgramStructure.cpp` | Defines and implements the program structure (metadata, parsers, controls, and deparsers) and parsing logic specific to the BMv2's PNA NIC backend. |
+| `midend.h`, `midend.cpp`     | Defines the mid-end processing of the PNA NIC compiler. Performs various transformations and optimizations on the program's Intermediate Representation (IR). |
+| `options.h`, `options.cpp`   | Manages the command-line options for the PNA NIC compiler. |
+| `pnaNic.h`, `pnaNic.cpp`     | Provides backend implementation to the BMv2's PNA NIC compiler. |
+| `main.cpp`                   | Sets up compilation environment, integrates various components, and executes the PNA NIC compiler. |
+| `version.h.cmake`            | Defines macros containing version information for the PNA NIC compiler. |

backends/bmv2/portable_common/README.md

@@ -1,21 +1,19 @@
-# portable_common
-
-This directory contains reusable components common to both the `psa_switch` and `pna_nic` backends.
-
-### midend.h, midend.cpp
+<!-- 
+Documentation Inclusion:
+This README is integrated as a subsection of the "Behavioral Model Backend" page in the P4 compiler documentation.
 
-Defines the common mid-end processing of both the `psa_switch` and `pna_nic` backends.
+Refer to the specific section here: [portable_common - Subsection](https://p4lang.github.io/p4c/behavioral_model_backend.html#portable_common)
+-->
 
-### options.h, options.cpp
-
-Defines the common command-line options of both the `psa_switch` and `pna_nic` backends.
-
-### portable.h, portable.cpp
+# portable_common
 
-Defines common functionalities that generate representations of P4 programs.
+The [`portable_common` directory](https://github.com/p4lang/p4c/tree/main/backends/bmv2/portable_common) contains reusable components common to both the `psa_switch` and `pna_nic` backends.
 
-The files `portableProgramStructure.h` and `portableProgramStructure.cpp` are in the `backends/common` directory.
 
-### portableProgramStructure.h, portableProgramStructure.cpp
 
-Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends.
+|      **File Name**          |      **Description**     |
+|-----------------------------|--------------------------|
+| **midend.h, midend.cpp**    | Defines the common mid-end processing of both the `psa_switch` and `pna_nic` backends.    |
+| **options.h, options.cpp**  | Defines the common command-line options of both the `psa_switch` and `pna_nic` backends.   |
+| **portable.h, portable.cpp**| Defines common functionalities that generate representations of P4 programs.   |
+| **portableProgramStructure.h, portableProgramStructure.cpp** | Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends. _These files are located in the `backends/common` directory._ |

backends/dpdk/README.md

@@ -1,5 +1,22 @@
-# DPDK backend
-
+<!--!
+\page dpdk_backend DPDK Backend                                                             
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [DPDK Backend](https://p4lang.github.io/p4c/dpdk_backend.html)
+-->
+<!--!
+\internal
+-->
+# DPDK Backend
+<!--!
+\endinternal
+-->
+<!--!
+[TOC]
+-->
 The **p4c-dpdk** backend translates the P4-16 programs to DPDK API to configure
 the DPDK software switch (SWX) pipeline. DPDK introduced the SWX pipeline in
 the DPDK 20.11 LTS release. For more information, please refer to the [release note](https://doc.dpdk.org/guides/rel_notes/release_20_11.html).

backends/ebpf/README.md

@@ -1,5 +1,23 @@
+<!--!
+\page ebpf_backend eBPF Backend                                                                     
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: https://p4lang.github.io/p4c/ebpf_backend.html
+-->
+<!--!
+\internal
+-->
 # eBPF Backend
+<!--!
+\endinternal
+-->
 
+<!--!
+[TOC]
+-->
 The back-end accepts only P4_16 code written for the `ebpf_model.p4` or
 `xdp_model.p4` filter models.  It generates C code that can be afterwards
 compiled into [eBPF (extended Berkeley Packet Filters)](https://en.wikipedia.org/wiki/Berkeley_Packet_Filter) using clang/llvm or
@@ -414,3 +432,7 @@ clang -O2 -include C-EXTERN-FILE.c -target bpf -c OUTPUT.c -o OUTPUT.o
   ```
 
   * The C extern function must not access BPF maps that are used to implement P4 tables and defined in the main C program generated from the P4 language.
+
+<!--!
+\include{doc} "../backends/ebpf/psa/README.md"
+-->

backends/ebpf/psa/README.md

@@ -1,6 +1,13 @@
+<!-- 
+Documentation Inclusion:
+This README is integrated as a subsection of the "eBPF Backend" page in the P4 compiler documentation.
+
+Refer to the specific section here: [PSA implementation for eBPF backend - Subsection](https://p4lang.github.io/p4c/pr-preview/4850/ebpf_backend.html#psa-implementation-for-ebpf-backend)
+-->
+
 # PSA implementation for eBPF backend
 
-This directory implements PSA (Portable Switch Architecture) for the eBPF backend.
+The [`backends/ebpf/psa` directory](https://github.com/p4lang/p4c/tree/main/backends/ebpf/psa) implements PSA (Portable Switch Architecture) for the eBPF backend.
 
 # Prerequisites
 

backends/graphs/README.md

@@ -1,5 +1,22 @@
+<!--!
+\page graphs_backend Graphs Backend                                                                  
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [Graphs Backend](https://p4lang.github.io/p4c/graphs_backend.html)
+-->
+<!--!
+\internal
+-->
 # Graphs Backend
-
+<!--!
+\endinternal
+-->
+<!--!
+[TOC]
+-->
 This backend produces visual representations of a P4 program as dot files. For
 now it supports the generation of graphs for top-level control and parser blocks,
 generation of fullGraph, which merges graphs for top-level program blocks and

backends/p4fmt/README.md

@@ -1,5 +1,22 @@
+<!--!
+\page p4fmt p4fmt (P4 Formatter)                                                               
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [p4fmt (P4 Formatter)](https://p4lang.github.io/p4c/p4fmt.html)
+-->
+<!--!
+\internal
+-->
 # p4fmt (P4 Formatter)
-
+<!--!
+\endinternal
+-->
+<!--!
+[TOC]
+-->
 p4fmt is a WIP formatter for P4. It's in a highly experimental phase
 and, not yet stable/reliable for general use.
 Contributions and feedbacks from the community