[DOCS][Refactor] Replace direct links with word links (#4577)

* [Refactor] Replace direct links with word links Refactor: replace direct links with word links in documentation * Refactor : Link to P4c Package on OpenSUSE * Refactor : Behavioral Model Backend Docs * Fix: Installation Guide link * Refactor: "Release note" Link in dpdk Backend * Refector : direct links in "ebpf" Backend * Refactor: Links in tc backend * Docs: Add P4TC tutorials * Fix: Broken Link to P4TC examples Repository * Refactor: Links in testdata\p4_16_samples * Fix: Wrongly formatted links * Refactor: Links in "Docs" Directory * Refactor: links in "Tools" directory * Fix: Remove outdated Doxygen generated Docs link
p4lang · Apr 2, 2024 · f203315 · f203315
1 parent a0520c8
commit f203315
Show file tree

Hide file tree

Showing 12 changed files with 26 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -22,9 +22,8 @@ make adding new backends easy.
 
 The code contains seven sample backends:
 * 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,
+  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),
 * p4c-ebpf: can be used to generate C code which can be compiled to [eBPF](https://en.wikipedia.org/wiki/Berkeley_Packet_Filter)
   and then loaded in the Linux kernel. The eBPF backend currently implements three architecture models:
   [ebpf_model.p4 for packet filtering, xdp_model.p4 for XDP](./backends/ebpf/README.md) and
@@ -136,7 +135,7 @@ If you cannot use a repository to install p4c, you can download the `.deb` file
 for your release and install it manually. You need to download a new file each
 time you want to upgrade p4c.
 
-1. Go to https://build.opensuse.org/package/show/home:p4lang/p4lang-p4c, click on
+1. Go to [p4lang-p4c package page on OpenSUSE Build Service](https://build.opensuse.org/package/show/home:p4lang/p4lang-p4c), click on
 "Download package" and choose your operating system version.
 
 2. Install p4c, changing the path below to the path where you downloaded the package.

diff --git a/backends/bmv2/README.md b/backends/bmv2/README.md
@@ -1,7 +1,6 @@
 # Behavioral Model Backend
 
-This is a back-end which generates code for the Behavioral Model version 2 (BMv2).
-https://github.com/p4lang/behavioral-model.git
+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
 `v1model.p4` switch model.
@@ -10,8 +9,7 @@ It can accept either P4_14 programs, or P4_16 programs written for the
 
 To run and test this back-end you need some additional tools:
 
-- the BMv2 behavioral model itself.  Installation instructions are available at
-  https://github.com/p4lang/behavioral-model.git.  You may need to update your
+- the BMv2 behavioral model itself.  Installation instructions are available [here](https://github.com/p4lang/behavioral-model#installing-bmv2).  You may need to update your
   dynamic libraries after installing bmv2: `sudo ldconfig`
 
 - the Python scapy library `sudo pip3 install scapy`

diff --git a/backends/dpdk/README.md b/backends/dpdk/README.md
@@ -2,8 +2,7 @@
 
 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 at https://doc.dpdk.org/guides/rel_notes/release_20_11.html.
+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).
 
 The p4c-dpdk compiler accepts P4-16 programs written for the Portable
 Switch Architecture (PSA) and Portable NIC Architecture (PNA) (see the

diff --git a/backends/ebpf/README.md b/backends/ebpf/README.md
@@ -2,12 +2,10 @@
 
 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
-bcc (https://github.com/iovisor/bcc.git).
+compiled into [eBPF (extended Berkeley Packet Filters)](https://en.wikipedia.org/wiki/Berkeley_Packet_Filter) using clang/llvm or
+[bcc](https://github.com/iovisor/bcc.git).
 
-An older version of this compiler for compiling P4_14 is available at
-https://github.com/iovisor/bcc/tree/master/src/cc/frontends/p4
+An older version of this compiler for compiling P4_14 is available [here](https://github.com/iovisor/bcc/tree/master/src/cc/frontends/p4).
 
 Identifiers starting with ebpf_ are reserved in P4 programs, including
 for structure field names.
@@ -173,8 +171,7 @@ eBPF continue to mature.
 The current version of the P4 to eBPF compiler translates programs
 written in the version P4_16 of the programming language to programs
 written in a restricted subset of C.  The subset of C is chosen such
-that it should be compilable to eBPF using clang and/or bcc (the BPF
-Compiler Collection -- https://github.com/iovisor/bcc).
+that it should be compilable to eBPF using clang and/or [bcc (the BPF Compiler Collection)](https://github.com/iovisor/bcc).
 
 ```
          --------------              -------
@@ -203,8 +200,8 @@ In addition the following packages and programs are required to run the full tes
 - Clang 3.3 and llvm 3.7.1 or later are required. (Note: In some
   versions of Ubuntu Xenial (16.04.4) CMake crashes when checking for
   llvm. Until the bugfix is committed upstream, workarounds are
-  available in the following issue:
-  https://github.com/p4lang/p4c/issues/1376
+  available in [this issue]( https://github.com/p4lang/p4c/issues/1376):
+
 
 - libpcap-dev to parse and generate .pcap files.
 
@@ -324,9 +321,7 @@ eBPF programs can be attached to it using the following command:
 
 `da` implies that tc takes action input directly from the return codes
 provided by the eBPF program. We currently support `TC_ACT_SHOT` and
-`TC_ACT_OK`. For more information, see this link:
-
-http://docs.cilium.io/en/latest/bpf/#tc-traffic-control
+`TC_ACT_OK`. More information avaiable [here](http://docs.cilium.io/en/latest/bpf/#tc-traffic-control).
 
 # How to run the generated eBPF program
 
@@ -336,8 +331,7 @@ the tables. The easiest and simplest way is to use the
 the kernel.
 
 An alternative is to use explicit syscalls (an example can be found in
-the [kernel tools
-folder](https://github.com/torvalds/linux/blob/master/tools/lib/bpf/bpf.c).
+the [kernel tools folder](https://github.com/torvalds/linux/blob/master/tools/lib/bpf/bpf.c).
 
 The P4 compiler automatically provides a set of table initializers,
 which may also serve as example, in the header of the generated

diff --git a/backends/p4tools/README.md b/backends/p4tools/README.md
@@ -53,8 +53,7 @@ for where to find/put what:
 
 P4Tools in general follows the [P4C coding style](https://github.com/p4lang/p4c/blob/main/docs/README.md#coding-conventions). Some deviations from the Style Guide are highlighted below.
 
-* Comments are important. The Style Guide's [section on
-  comments](https://google.github.io/styleguide/cppguide.html#Comments) is
+* Comments are important. The Style Guide's [section on comments](https://google.github.io/styleguide/cppguide.html#Comments) is
   required reading.
     * Classes, methods, and fields are documented with triple-slash
       Doxygen-style comments:

diff --git a/backends/tc/README.md b/backends/tc/README.md
@@ -4,8 +4,9 @@ TC backend aims to generate files for the P4TC implementation in Linux kernel (f
 
 For more info on P4TC, Please refer:
 
-* https://github.com/p4tc-dev/docs/blob/main/why-p4tc.md
-* https://github.com/p4tc-dev/p4tc-v2-examples
+* [What Is P4TC](https://github.com/p4tc-dev/docs/blob/main/why-p4tc.md)
+* [P4TC examples](https://github.com/p4tc-dev/p4tc-examples-pub)
+* [P4TC tutorial](https://github.com/p4tc-dev/p4tc-tutorial-pub)
 
 The p4c-pna-p4tc compiler accepts the P4-16 programs written for the pna.p4 architecture model.
 

diff --git a/docs/IR.md b/docs/IR.md
@@ -46,7 +46,7 @@ object, recursively.
 ## Visitors and Transforms
 
 The compiler is organized as a series of `Visitor` and `Transform`
-passes (https://en.wikipedia.org/wiki/Visitor_pattern).  The `Visitor`
+passes [Wikipedia](https://en.wikipedia.org/wiki/Visitor_pattern).  The `Visitor`
 and `Transform` base classes make defining new passes easy -- a new
 transform need only specify the IR types it is interested in, and can
 ignore others.  A (constant) `Visitor` pass visits every node in the

diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,7 @@
 # Repository
 
 This folder contains documentation for the P4_16 prototype compiler.
-The code and documentation are hosted in the following repository: https://github.com/p4lang/p4c
+The code and documentation are hosted in the [p4c repository](https://github.com/p4lang/p4c). 
 
 # Compiler source code organization
 
@@ -99,8 +99,7 @@ p4c
 Documenting the workings of the compiler is a never-ending (many times
 overlooked) job. We can always write better documentation!
 
-In P4C, documentation is generated using Doxygen
-(http://www.stack.nl/~dimitri/doxygen/index.html). There are two main
+In P4C, documentation is generated using Doxygen. There are two main
 sources from which we generate documentation: comments in the code and
 markup documents in the docs/doxygen directory.
 
@@ -130,8 +129,7 @@ Happy writing! Should you have any questions, please don't hesitate to ask.
 
 ## Git usage
 
-* To contribute: fork the p4lang/p4c repository on github
-  (see https://help.github.com/articles/fork-a-repo/)
+* To contribute: fork the p4lang/p4c repository on github.  [Detailed instructions on forking a repository](https://help.github.com/articles/fork-a-repo/).
 * To merge a forked repository with the latest changes in the source use:
 
 ```

diff --git a/testdata/p4_16_samples/dash/README.md b/testdata/p4_16_samples/dash/README.md
@@ -1,7 +1,7 @@
 # DASH P4 Programs
 The Disaggregated API for SONiC Hosts (DASH) defines a behavioral model for conformance testing of network devices. The P4 programs contained here model various network architecture scenarios related to the DASH project.
 
-They are sourced from https://github.com/sonic-net/DASH. For more information, please see https://github.com/sonic-net/DASH/blob/main/documentation/general/dash-high-level-design.md.
+They are sourced from [DASH repository on GitHub](https://github.com/sonic-net/DASH). For more information, please see [DASH High-Level Design document](https://github.com/sonic-net/DASH/blob/main/documentation/general/dash-high-level-design.md).
 
 To refresh the DASH programs used here, please use the following commands:
 

diff --git a/testdata/p4_16_samples/omec/README.md b/testdata/p4_16_samples/omec/README.md
@@ -1,3 +1,3 @@
 # OMEC P4 Programs
 The P4 programs contained here model a virtual User Plane Function (UPF) pipeline as part of the SD-Fabric project. up4.p4 is a One-Big-UPF abstraction, a program that doesn't run on switches, but is used as the schema to define the content of the P4Runtime messages that can be exchanged with the UP4 app.
-They are sourced from https://github.com/omec-project/up4. For more information, please see https://docs.sd-fabric.org/master/advanced/p4-upf.html.
+They are sourced from [up4 repository](https://github.com/omec-project/up4). For more information, please see [P4 UPF Documentation](https://docs.sd-fabric.org/master/advanced/p4-upf.html).
diff --git a/testdata/p4_16_samples/pins/README.md b/testdata/p4_16_samples/pins/README.md
@@ -1,3 +1,3 @@
 # PINS P4 Programs
 
-These P4 programs are P4 models of production switches. They are sourced from https://github.com/sonic-net/sonic-pins/tree/main/sai_p4/instantiations/google. For more information, please see https://sonic-net.github.io/SONiC/.
+These P4 programs are P4 models of production switches. They are sourced from [sonic-pins repository](https://github.com/sonic-net/sonic-pins/tree/main/sai_p4/instantiations/google). For more information, please see [SONiC website](https://sonic-net.github.io/SONiC/).
diff --git a/tools/README.md b/tools/README.md
@@ -5,8 +5,7 @@ Contains utility scripts for supporting the development of P4C.
 
 [IWYU](https://github.com/include-what-you-use/include-what-you-use) checks that every symbol used in a C/C++ file has a corresponding include. Vice-versa IWYU also ensures that unnecessary includes are removed.
 
-Since it depends on clang and LLVM, it is recommended to install IWYU from scratch using the following instructions:
-https://github.com/include-what-you-use/include-what-you-use#how-to-build-standalone
+Since it depends on clang and LLVM, it is recommended to install IWYU from scratch.[Instructions to Build IWYU Standalone](https://github.com/include-what-you-use/include-what-you-use#how-to-build-standalone)
 
 To use IWYU for P4Tools, enable it first in the build order with the option
 ```