Docs : Content Organization and Documentation Updates (#4850)

* Create Subsections of related topics Signed-off-by: Adarsh <[email protected]> * Remove Revision History Signed-off-by: Adarsh <[email protected]> * Exclude Subsections from generated Documentation Signed-off-by: Adarsh <[email protected]> * Remove: deprecated Section from generated docs Signed-off-by: Adarsh <[email protected]> * Disable Todo list Signed-off-by: Adarsh <[email protected]> * Docs : Hide Namespace and Classes section from output Signed-off-by: Adarsh <[email protected]> * Merge P4C Overview with P4C root README Signed-off-by: Adarsh <[email protected]> * Minor Fix : missing "`" in directory structure Signed-off-by: Adarsh <[email protected]> * Remove Revision History Signed-off-by: Adarsh <[email protected]> * Merge P4C Overview with P4C root README Signed-off-by: Adarsh <[email protected]> * Disable Auto Link support for classes/namespaces Signed-off-by: Adarsh <[email protected]> * Merge "Common P4C Utility Functions" as a subsection of "P4C" Page Signed-off-by: Adarsh <[email protected]> * Convert file descriptions to Markdown table format in BMv2 "pna_nic" Backend Signed-off-by: Adarsh <[email protected]> * Remove Revision History Signed-off-by: Adarsh <[email protected]> * Merge P4C Overview with P4C root README Signed-off-by: Adarsh <[email protected]> * Remove Revision History Signed-off-by: Adarsh <[email protected]> * Merge P4C Overview with P4C root README Signed-off-by: Adarsh <[email protected]> * Content for P4test Backend Signed-off-by: Adarsh <[email protected]> * Refactor : Organize `portable_common` directory file descriptions Organize `portable_common` directory file descriptions into a table format Signed-off-by: Adarsh <[email protected]> * Hide Doxygen Commands from GitHub Markdown render Using the New Doxygen comment style in v1.12.0 i.e. `` For details - #4861 Signed-off-by: Adarsh <[email protected]> * Create Subsections of related topics Signed-off-by: Adarsh <[email protected]> * Docs : Hide Namespace and Classes section from output Signed-off-by: Adarsh <[email protected]> * Merge P4C Overview with P4C root README Signed-off-by: Adarsh <[email protected]> * Remove Revision History Signed-off-by: Adarsh <[email protected]> * Merge P4C Overview with P4C root README Signed-off-by: Adarsh <[email protected]> * Content for P4test Backend Signed-off-by: Adarsh <[email protected]> * Fix : removed extra Command Signed-off-by: Adarsh <[email protected]> * Organize `IR` Classes descriptions into a table format Signed-off-by: Adarsh <[email protected]> * chore: Add TOC to content-rich pages Signed-off-by: Adarsh <[email protected]> * Remove TOC from Changelogs Signed-off-by: Adarsh <[email protected]> * Exclude GitHub markdown TOC from Doxygen output Signed-off-by: Adarsh <[email protected]> * Highlight sample backends in P4C with a dedicated heading Signed-off-by: Adarsh <[email protected]> * Merged: BMv2 "pna_nic" Backend into Behavioral Model Backend Signed-off-by: Adarsh <[email protected]> * Merge P4C IR Classes into IR Page Signed-off-by: Adarsh <[email protected]> * Change the top of tree view from "P4C" -> "P4 Compiler Documentation (P4C)" Signed-off-by: Adarsh <[email protected]> * Change root page heading "P4C" -> "Getting Started" Signed-off-by: Adarsh <[email protected]> * Move changelogs to the end of Side bar Signed-off-by: Adarsh <[email protected]> * Improve Getting started page heading Signed-off-by: Adarsh <[email protected]> * Merge "portable_common" section under "bmv2" Signed-off-by: Adarsh <[email protected]> * Minor formatting Fixes Signed-off-by: Adarsh <[email protected]> * Minor command fix Signed-off-by: Adarsh <[email protected]> * Fix: Broken Table structure in Doxygen output Signed-off-by: Adarsh <[email protected]> * Refactor : Page headings Signed-off-by: Adarsh <[email protected]> * Refactor : Ordering of backends Signed-off-by: Adarsh <[email protected]> * Enable Nice URL for generated docs Current default doxygen URL config Output- https://p4lang.github.io/p4c/md__2home_2runner_2work_2p4c_2p4c_2backends_2dpdk_2_r_e_a_d_m_e.html Updated - https://p4lang.github.io/p4c/dpdk_backend.html Signed-off-by: Adarsh <[email protected]> * Doc: Add inclusion notes to Documented Markdown files - Added comments to indicate whether each README is included as a standalone page, a subsection, or not included in the P4 compiler documentation. - Provided specific links to relevant sections or pages within the documentation. Signed-off-by: Adarsh <[email protected]> * Docs: Add remaining documentation inclusion notes Signed-off-by: Adarsh <[email protected]> * Add GitHub profile links for Core developers of p4tools Compatible with GitHub and Doxygen Signed-off-by: Adarsh <[email protected]> * Fix: formatting of inclusion note Signed-off-by: Adarsh <[email protected]> * Docs: Side bar grouping of backends Signed-off-by: Adarsh <[email protected]> * Add Introduction for Frontend and Midend Signed-off-by: Adarsh <[email protected]> * Update lib/README.md Signed-off-by: Adarsh <[email protected]> Co-authored-by: Fabian Ruffy <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> * Revert: Changes that are migrated to PR #4876 Signed-off-by: Adarsh <[email protected]> --------- Signed-off-by: Adarsh <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> Co-authored-by: Fabian Ruffy <[email protected]>
p4lang · Aug 19, 2024 · c9fe41c · c9fe41c
1 parent 39d9d44
commit c9fe41c
Show file tree

Hide file tree

Showing 34 changed files with 571 additions and 88 deletions.
diff --git a/CHANGELOG.md b/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.

diff --git a/CONTRIBUTING.md b/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" 
+-->
diff --git a/README.md b/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

diff --git a/backends/bmv2/README.md b/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" 
+-->
diff --git a/backends/bmv2/pna_nic/README.md b/backends/bmv2/pna_nic/README.md
@@ -1,6 +1,13 @@
+<!-- 
+Documentation Inclusion:
+This README is integrated as a subsection of the "Behavioral Model Backend" page in the P4 compiler documentation.
+
+Refer to the specific section here: [BMv2 "pna_nic" Backend - Subsection](https://p4lang.github.io/p4c/behavioral_model_backend.html#bmv2-pna_nic-backend)
+-->
+
 # 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.
+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.
 
 Output Binary: `p4c-bm2-pna`
 
@@ -26,4 +33,4 @@ Sets up compilation environment, integrates various components, and executes the
 
 ##### version.h.cmake
 
-Defines macros containing version information for the PNA NIC compiler.
+Defines macros containing version information for the PNA NIC compiler.
diff --git a/backends/bmv2/portable_common/README.md b/backends/bmv2/portable_common/README.md
@@ -1,3 +1,9 @@
+<!-- 
+Documentation Inclusion:
+This README is integrated as a subsection of the "Behavioral Model Backend" page in the P4 compiler documentation.
+
+Refer to the specific section here: [portable_common - Subsection](https://p4lang.github.io/p4c/behavioral_model_backend.html#portable_common)
+-->
 # portable_common
 
 This directory contains reusable components common to both the `psa_switch` and `pna_nic` backends.
@@ -18,4 +24,4 @@ The files `portableProgramStructure.h` and `portableProgramStructure.cpp` are in
 
 ### portableProgramStructure.h, portableProgramStructure.cpp
 
-Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends.
+Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends.
diff --git a/backends/dpdk/README.md b/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).

diff --git a/backends/ebpf/README.md b/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"
+-->
diff --git a/backends/ebpf/psa/README.md b/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
 

diff --git a/backends/graphs/README.md b/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

diff --git a/backends/p4fmt/README.md b/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

diff --git a/backends/p4test/README.md b/backends/p4test/README.md
@@ -1,3 +1,21 @@
+<!--!
+\page p4test_backend P4test Backend                                                               
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [P4test Backend](https://p4lang.github.io/p4c/p4test_backend.html)
+-->
+<!--!
+\internal
+-->
 # P4test Backend
+<!--!
+\endinternal
+-->
 
-This is a "fake" backend, whose sole purpose is to test the P4-16 front-end.
+<!--!
+[TOC]
+-->
+This is a "fake" backend, whose sole purpose is to test the P4-16 front-end.
diff --git a/backends/p4tools/CONTRIBUTORS.md b/backends/p4tools/CONTRIBUTORS.md
@@ -1,3 +1,10 @@
+<!-- 
+Documentation Inclusion:
+This README is integrated as a subsection of the "P4Tools" page in the P4 compiler documentation.
+
+Refer to the specific section here: [P4Tools Contributors
+ - Subsection](https://p4lang.github.io/p4c/pr-preview/4850/p4tools.html#p4tools-contributors)
+-->
 # P4Tools Contributors
 
 P4Testgen is a test oracle for the P4 language. Given a P4_16 program and a specification of the underlying architecture, it automatically generates a comprehensive set of input/output tests that can be executed to validate a target device.

diff --git a/backends/p4tools/README.md b/backends/p4tools/README.md
@@ -1,4 +1,29 @@
-# P4Tools - Testing Tools For P4 Targets
+<!--!
+\page p4tools P4Tools                                                               
+-->
+<!-- 
+Documentation Inclusion:
+This README is integrated as a standalone page in the P4 compiler documentation.
+
+Refer to the full page here: [P4Tools](https://p4lang.github.io/p4c/p4tools.html)
+-->
+<!--!
+\internal
+-->
+# P4Tools 
+<!--!
+\endinternal
+-->
+
+<!--!
+[TOC]
+-->
+P4Tools is a collection of tools that make testing P4 targets and programs a little easier. So far the platform supports the following tools and projects:
+
+- [P4Testgen](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/testgen): An input-output test case generator for P4.
+
+- [P4Smith](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/smith): A random P4 program generator in the spirit of Csmith.
+
 
 ## Directory Structure
 
@@ -15,13 +40,6 @@ p4tools
     └─ testgen       ── P4Testgen: a test-case generator for P4 programs.
 ```
 
-## P4Tools
-P4Tools is a collection of tools that make testing P4 targets and programs a little easier. So far the platform supports the following tools and projects:
-
-- [P4Testgen](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/testgen): An input-output test case generator for P4.
-
-- [P4Smith](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/smith): A random P4 program generator in the spirit of Csmith.
-
 ## Building
 Please see the general installation instructions [here](https://github.com/p4lang/p4c#installing-p4c-from-source). P4Tools can be built using the following CMAKE configuration in the P4C repository.
 
@@ -69,3 +87,6 @@ P4Tools in general follows the [P4C coding style](https://github.com/p4lang/p4c/
   library of related classes. Multiple classes may be declared in a `.cpp`
   file.
 
+<!--! 
+\include{doc} "../backends/p4tools/CONTRIBUTORS.md"
+-->