Sync docs structure with P4 repo

docs/README.md

@@ -130,8 +130,10 @@ overlooked) job. We can always write better documentation!
 
 In P4C, documentation is generated using Doxygen. The generated documentation depends on [Doxygen Awesome CSS](https://github.com/jothepro/doxygen-awesome-css). The documentation is dynamically updated and deployed on [GitHub Pages](https://p4lang.github.io/p4c/).
 
-There are two main sources from which we generate documentation: comments
-in the code and markup documents in the docs/doxygen directory.
+Documentation is generated from two main sources: README files distributed 
+across the repository and comments within the code. The README files are 
+tagged with documentation inclusion notes to indicate their integration into 
+the P4 compiler documentation.
 
 Code comments should capture the main intent of the implementation and
 the "why", rather than the "how". The how can be read from the code,
@@ -150,14 +152,45 @@ XX is a number between 02-99. Currently, 00_revision_history.md
 contains the documentation revision history, and 01_overview.md is the
 overview of the compiler goals and architecture.
 
-## Documentation Comments Style Guide 
+## C/C++ Documentation Comments Style Guide 
 - Use triple slashes `///` for documenting functions and classes in files.
 - Double slashes `//` should be used for "internal" comments within functions.
 - Double slashes `//` should be used for inline comment.
 - For rare occasions such as adding comments to multi-line macros, you may use `/* ... */` style comments.
-- There should be no space at the end of the comment.
-- First letter of the comment should be a capital letter.
-- Each comment should end with a period.
+- Formatting:
+  - There should be no space at the end of the comment.
+  - First letter of the comment should be a capital letter.
+  - Each comment should end with a period.
+
+## Building the Doxygen documentation
+- Doxygen is configured in `docs/doxygen/doxygen.cfg`.
+- The main HTML page is configured in `docs/doxygen/Doxymain.md`:
+  - CSS for the card effect is in `docs/assets/css/card.css`.
+  - The effect for the Easter egg toggle is defined in `docs/assets/css/flow.css`. 
+  - The homepage P4C architecture is rendered using `docs/assets/architecture_unanimated.html`, with the editable draw file available at `docs/assets/Architecture.drawio`.
+- Add pages and subpages manually to the sidebar (see `docs/doxygen/p4c_layout.xml`).
+- TOCs in markdown files are created with the `[TOC]` command.
+- The base style for Doxygen Awesome is described in the [Doxygen Awesome Documentation](https://jothepro.github.io/doxygen-awesome-css/) and the updated color scheme is defined in [`docs\assets\css\p4c_custom.css`](https://github.com/p4lang/p4c/blob/main/docs/assets/css/p4c_custom.css).
+
+### Doxygen Comments Style Guide
+- Comment Markup and Documentation Commands
+  -  `<!-- ... -->` is used for adding documentation inclusion notes. This content is hidden from both the rendered Markdown and Doxygen, but visible in the raw view on GitHub.
+  - Use HTML comments with an exclamation mark to add instructions for Doxygen. These comments are hidden in GitHub's Markdown but processed by Doxygen. For example:
+``` 
+<!--!
+\page changelog Releases
+-->
+```
+  -  `\internal` and `\endinternal` commands within comments can be used to hide information from Doxygen while still displaying it on GitHub.
+```
+<!--!
+\internal
+-->
+This section is hidden from Doxygen but will be visible on GitHub.
+<!--!
+\endinternal
+-->
+```
 
 Happy writing! Should you have any questions, please don't hesitate to ask.
 
@@ -178,6 +211,23 @@ git push -f
   [guidelines](CodingStandardPhilosophy.md#git-commits-and-pull-requests)
   to write commit messages and open pull requests.
 
++ For every pull request opened, a standard set of CI tests will run
+  automatically.  If any of these fail, look at the Github page for
+  your pull request for the list of tests that have been run.  There
+  should be "Details" links there for any tests that have failed.  Ask
+  for help via messages in comments on your PR if you are not able to
+  determine the cause of the failures.
+
++ There are several CI tests that are not run on every pull request
+  automatically, but only via following the steps below, in order to
+  reduce the compute resources used on every pull request.  If you
+  wish to run one or more of these, look through the list of Github
+  labels for the p4c project
+  [here](https://github.com/p4lang/p4c/labels) for labels whose name
+  begins with "run-".  Add one or more of those labels to your PR.
+  On all future pushes to the branch of that PR, those additional CI
+  runs should run.
+
 ## Debugging
 
 * To debug the build process you can run `make V=1`

docs/doxygen/bfn_header.tex

@@ -96,7 +96,6 @@
 \fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize Barefoot Networks }}
 \fancyfoot[CO]{\fancyplain{}{}}
 \fancyfoot[RO]{\fancyplain{}{}}
-%\fancyfoot[C]{\sffamily\scriptsize\textbf{Company Confidential}}
 \renewcommand{\footrulewidth}{0.4pt}
 \renewcommand{\sectionmark}[1]{%
   \markright{\thesection\ #1}%

docs/doxygen/doxygen.cfg

@@ -1,4 +1,4 @@
-# Doxyfile 1.12.0
+# Doxyfile 1.13.2
 
 # This file describes the settings to be used by the documentation system
 # Doxygen (www.doxygen.org) for a project.
@@ -42,7 +42,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = P4 Compiler Documentation (P4C)
+PROJECT_NAME           = "P4 Compiler Documentation (P4C)"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -51,7 +51,7 @@ PROJECT_NAME           = P4 Compiler Documentation (P4C)
 PROJECT_NUMBER         =
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
-# for a project that appears at the top of each page and should give viewer a
+# for a project that appears at the top of each page and should give viewers a
 # quick idea about the purpose of the project. Keep the description short.
 
 PROJECT_BRIEF          = "The P4 Compiler"
@@ -80,7 +80,7 @@ OUTPUT_DIRECTORY       = ./build
 # sub-directories (in 2 levels) under the output directory of each output format
 # and will distribute the generated files over these directories. Enabling this
 # option can be useful when feeding Doxygen a huge amount of source files, where
-# putting all generated files in the same directory would otherwise causes
+# putting all generated files in the same directory would otherwise cause
 # performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to
 # control the number of sub-directories.
 # The default value is: NO.
@@ -192,17 +192,17 @@ STRIP_FROM_PATH        =
 STRIP_FROM_INC_PATH    =
 
 # If the SHORT_NAMES tag is set to YES, Doxygen will generate much shorter (but
-# less readable) file names. This can be useful is your file systems doesn't
+# less readable) file names. This can be useful if your file system doesn't
 # support long names like on DOS, Mac, or CD-ROM.
 # The default value is: NO.
 
 SHORT_NAMES            = NO
 
 # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen will interpret the
-# first line (until the first dot) of a Javadoc-style comment as the brief
-# description. If set to NO, the Javadoc-style will behave just like regular Qt-
-# style comments (thus requiring an explicit @brief command for a brief
-# description.)
+# first line (until the first dot, question mark or exclamation mark) of a
+# Javadoc-style comment as the brief description. If set to NO, the Javadoc-
+# style will behave just like regular Qt-style comments (thus requiring an
+# explicit @brief command for a brief description.)
 # The default value is: NO.
 
 JAVADOC_AUTOBRIEF      = NO
@@ -218,9 +218,10 @@ JAVADOC_AUTOBRIEF      = NO
 JAVADOC_BANNER         = NO
 
 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will interpret the first
-# line (until the first dot) of a Qt-style comment as the brief description. If
-# set to NO, the Qt-style will behave just like regular Qt-style comments (thus
-# requiring an explicit \brief command for a brief description.)
+# line (until the first dot, question mark or exclamation mark) of a Qt-style
+# comment as the brief description. If set to NO, the Qt-style will behave just
+# like regular Qt-style comments (thus requiring an explicit \brief command for
+# a brief description.)
 # The default value is: NO.
 
 QT_AUTOBRIEF           = NO
@@ -373,11 +374,20 @@ MARKDOWN_ID_STYLE      = GITHUB
 # When enabled Doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can
 # be prevented in individual cases by putting a % sign in front of the word or
-# globally by setting AUTOLINK_SUPPORT to NO.
+# globally by setting AUTOLINK_SUPPORT to NO. Words listed in the
+# AUTOLINK_IGNORE_WORDS tag are excluded from automatic linking.
 # The default value is: YES.
 
 AUTOLINK_SUPPORT       = NO
 
+# This tag specifies a list of words that, when matching the start of a word in
+# the documentation, will suppress auto links generation, if it is enabled via
+# AUTOLINK_SUPPORT. This list does not affect affect links explicitly created
+# using \# or the \link or commands.
+# This tag requires that the tag AUTOLINK_SUPPORT is set to YES.
+
+AUTOLINK_IGNORE_WORDS  =
+
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should set this
 # tag to YES in order to let Doxygen match functions declarations and
@@ -589,6 +599,14 @@ HIDE_UNDOC_MEMBERS     = NO
 
 HIDE_UNDOC_CLASSES     = NO
 
+# If the HIDE_UNDOC_NAMESPACES tag is set to YES, Doxygen will hide all
+# undocumented namespaces that are normally visible in the namespace hierarchy.
+# If set to NO, these namespaces will be included in the various overviews. This
+# option has no effect if EXTRACT_ALL is enabled.
+# The default value is: YES.
+
+HIDE_UNDOC_NAMESPACES  = YES
+
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all friend
 # declarations. If set to NO, these declarations will be included in the
 # documentation.
@@ -956,6 +974,7 @@ WARN_LOGFILE           = p4c-doxygen-warn.log
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                 = ../../docs/README.md \
+                        ../../frontends/README.md \
                         ../../README.md \ 
                         ../../docs/doxygen \
                         ../../frontends \
@@ -990,10 +1009,10 @@ INPUT                 = ../../docs/README.md \
 INPUT_ENCODING         = UTF-8
 
 # This tag can be used to specify the character encoding of the source files
-# that Doxygen parses The INPUT_FILE_ENCODING tag can be used to specify
+# that Doxygen parses. The INPUT_FILE_ENCODING tag can be used to specify
 # character encoding on a per file pattern basis. Doxygen will compare the file
 # name with each pattern and apply the encoding instead of the default
-# INPUT_ENCODING) if there is a match. The character encodings are a list of the
+# INPUT_ENCODING if there is a match. The character encodings are a list of the
 # form: pattern=encoding (like *.php=ISO-8859-1).
 # See also: INPUT_ENCODING for further information on supported encodings.
 
@@ -1035,7 +1054,6 @@ RECURSIVE              = YES
 # run.
 
 EXCLUDE                = ../../frontends/p4/README.md \
-                         ../../midend/README.md \
                          ./awesome_css \
                          ./build \
                          ../../backends/p4tools/cmake/README.md \
@@ -1052,9 +1070,9 @@ EXCLUDE                = ../../frontends/p4/README.md \
                          ../../docs/doxygen/01_overview.md \
                          ../../docs/doxygen/00_revision_history.md \
                          ../../lib/README.md \
-                         ../../backends/bmv2/pna_nic/README.md  \
+                         ../../backends/bmv2/pna_nic/README.md \
                          ../../ir/README.md \
-                         ../../backends/bmv2/portable_common/README.md \
+                         ../../backends/bmv2/portable_common/README.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1171,6 +1189,15 @@ FILTER_SOURCE_PATTERNS =
 
 USE_MDFILE_AS_MAINPAGE = ./Doxymain.md
 
+# If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub-
+# directories of the project's root, is used as the documentation for that sub-
+# directory, except when the README.md starts with a \dir, \page or \mainpage
+# command. If set to NO, the README.md file needs to start with an explicit \dir
+# command in order to be used as directory documentation.
+# The default value is: YES.
+
+IMPLICIT_DIR_DOCS      = YES
+
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common
 # extension is to allow longer lines before the automatic comment starts. The
@@ -1588,9 +1615,9 @@ DOCSET_PUBLISHER_NAME  = Publisher
 # additional HTML index files: index.hhp, index.hhc, and index.hhk. The
 # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop
 # on Windows. In the beginning of 2021 Microsoft took the original page, with
-# a.o. the download links, offline the HTML help workshop was already many years
-# in maintenance mode). You can download the HTML help workshop from the web
-# archives at Installation executable (see:
+# a.o. the download links, offline (the HTML help workshop was already many
+# years in maintenance mode). You can download the HTML help workshop from the
+# web archives at Installation executable (see:
 # http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo
 # ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe).
 #
@@ -1749,7 +1776,7 @@ ECLIPSE_DOC_ID         = org.doxygen.Project
 # of each HTML page. A value of NO enables the index and the value YES disables
 # it. Since the tabs in the index contain the same information as the navigation
 # tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES.
-# The default value is: NO.
+# The default value is: YES.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
 DISABLE_INDEX          = NO
@@ -1766,7 +1793,7 @@ DISABLE_INDEX          = NO
 # shows how to put an image at the root of the tree instead of the PROJECT_NAME.
 # Since the tree basically has the same information as the tab index, you could
 # consider setting DISABLE_INDEX to YES when enabling this option.
-# The default value is: NO.
+# The default value is: YES.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
 GENERATE_TREEVIEW      = YES
@@ -2178,7 +2205,7 @@ LATEX_HIDE_INDICES     = NO
 # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
 # bibliography, e.g. plainnat, or ieeetr. See
 # https://en.wikipedia.org/wiki/BibTeX and \cite for more info.
-# The default value is: plain.
+# The default value is: plainnat.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
 LATEX_BIB_STYLE        = plain
@@ -2785,24 +2812,29 @@ DIR_GRAPH_MAX_DEPTH    = 1
 # generated by dot. For an explanation of the image formats see the section
 # output formats in the documentation of the dot tool (Graphviz (see:
 # https://www.graphviz.org/)).
-# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order
-# to make the SVG files visible in IE 9+ (other browsers do not have this
-# requirement).
+#
+# Note the formats svg:cairo and svg:cairo:cairo cannot be used in combination
+# with INTERACTIVE_SVG (the INTERACTIVE_SVG will be set to NO).
 # Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo,
-# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and
-# png:gdiplus:gdiplus.
+# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus,
+# png:gdiplus:gdiplus, svg:cairo, svg:cairo:cairo, svg:svg, svg:svg:core,
+# gif:cairo, gif:cairo:gd, gif:cairo:gdiplus, gif:gdiplus, gif:gdiplus:gdiplus,
+# gif:gd, gif:gd:gd, jpg:cairo, jpg:cairo:gd, jpg:cairo:gdiplus, jpg:gd,
+# jpg:gd:gd, jpg:gdiplus and jpg:gdiplus:gdiplus.
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_IMAGE_FORMAT       = svg
 
-# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
-# enable generation of interactive SVG images that allow zooming and panning.
+# If DOT_IMAGE_FORMAT is set to svg or svg:svg or svg:svg:core, then this option
+# can be set to YES to enable generation of interactive SVG images that allow
+# zooming and panning.
 #
 # Note that this requires a modern browser other than Internet Explorer. Tested
 # and working are Firefox, Chrome, Safari, and Opera.
-# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make
-# the SVG files visible. Older versions of IE do not have SVG support.
+#
+# Note This option will be automatically disabled when DOT_IMAGE_FORMAT is set
+# to svg:cairo or svg:cairo:cairo.
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
@@ -2852,6 +2884,12 @@ PLANTUML_CFG_FILE      =
 
 PLANTUML_INCLUDE_PATH  =
 
+# The PLANTUMLFILE_DIRS tag can be used to specify one or more directories that
+# contain PlantUml files that are included in the documentation (see the
+# \plantumlfile command).
+
+PLANTUMLFILE_DIRS      =
+
 # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes
 # that will be shown in the graph. If the number of nodes in a graph becomes
 # larger than this value, Doxygen will truncate the graph, which is visualized