Include our Markdown documentation in the Doxygen site. (#8417)

A few quirks in the Markdown parser were worked around here.

The most notable is that the sequence `]:` causes Doxygen to interpret a
would-be link as a trailing reference even if it is not at the start of
a line. Duplicating the single bracket reference is a portable
workaround, i.e.

    [winget]  ~>  [winget][winget]

It also doesn't stop interpreting `@` directives inside inline code, so
it warns about our use of the `@` as a decorator symbol inside
Python.md.

Author: alexreinking

Makefile

@@ -2560,15 +2560,17 @@ CLASS_DIAGRAMS         = NO
 DISTRIBUTE_GROUP_DOC   = YES
 EXAMPLE_PATH           = "${Halide_SOURCE_DIR}/tutorial"
 EXCLUDE                = bin
+EXCLUDE_PATTERNS       = README.md
 EXTRACT_ALL            = YES
 EXTRACT_LOCAL_CLASSES  = NO
-FILE_PATTERNS          = *.h
+FILE_PATTERNS          = *.h *.md
 GENERATE_TREEVIEW      = YES
 HIDE_FRIEND_COMPOUNDS  = YES
 HIDE_IN_BODY_DOCS      = YES
 HIDE_UNDOC_CLASSES     = YES
 HIDE_UNDOC_MEMBERS     = YES
 JAVADOC_AUTOBRIEF      = YES
+MARKDOWN_ID_STYLE      = GITHUB
 QT_AUTOBRIEF           = YES
 QUIET                  = YES
 RECURSIVE              = YES
@@ -2583,7 +2585,7 @@ STRIP_CODE_COMMENTS    = NO
 GENERATE_LATEX         = NO
 HAVE_DOT               = NO
 HTML_OUTPUT            = .
-INPUT                  = "${Halide_SOURCE_DIR}/src" "${Halide_SOURCE_DIR}/test"
+INPUT                  = "${Halide_SOURCE_DIR}/doc" "${Halide_SOURCE_DIR}/src" "${Halide_SOURCE_DIR}/test"
 OUTPUT_DIRECTORY       = ${DOC_DIR}
 PROJECT_NAME           = Halide
 endef

doc/BuildingHalideWithCMake.md

@@ -82,7 +82,7 @@ directions posted on [Kitware's website][cmake-from-source].
 On Windows, there are two primary methods for installing an up-to-date CMake:
 
 1. You can get CMake through the Visual Studio 2022 installer.
-2. You can use Windows's built-in package manager, [winget]:
+2. You can use Windows's built-in package manager, [winget][winget]:
    ```shell
    winget install Kitware.CMake
    ```
@@ -105,8 +105,8 @@ There are a few good ways to install CMake on Ubuntu:
 1. If you're running 24.04 LTS, then simply running
    `sudo apt install cmake` will install CMake 3.28.
 2. If you're running an older LTS or would like to use the newest CMake, try
-   installing via the [snap store]: `snap install cmake`. Note this will
-   conflict with an APT-provided CMake.
+   installing via the [snap store][snap store]: `snap install cmake`. Note this
+   will conflict with an APT-provided CMake.
 3. Kitware also provides an [APT repository][cmake-apt] with up-to-date
    releases. Compatible with 20.04 LTS+ and is the best option for 32-bit ARM.
 
@@ -215,7 +215,7 @@ appropriately per-platform. They are documented further below.
 On Windows, we recommend using `vcpkg` to install library dependencies.
 
 To build the documentation, you will need to install [Doxygen]. This can be done
-either from the [Doxygen website][doxygen-download] or through [winget]:
+either from the [Doxygen website][doxygen-download] or through [winget][winget]:
 
 ```shell
 $ winget install DimitriVanHeesch.Doxygen
@@ -623,4 +623,4 @@ Python and C++ `find_package` workflows.
 
 [wabt]: https://github.com/WebAssembly/wabt
 
-[winget]: https://learn.microsoft.com/en-us/windows/package-manager/winget/
+[winget]: https://learn.microsoft.com/en-us/windows/package-manager/winget/

doc/CMakeLists.txt

@@ -8,15 +8,17 @@ set(DOXYGEN_CLASS_DIAGRAMS NO)
 set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES)
 set(DOXYGEN_EXAMPLE_PATH "${Halide_SOURCE_DIR}/tutorial")
 set(DOXYGEN_EXCLUDE bin)
+set(DOXYGEN_EXCLUDE_PATTERNS README.md)
 set(DOXYGEN_EXTRACT_ALL YES)
 set(DOXYGEN_EXTRACT_LOCAL_CLASSES NO)
-set(DOXYGEN_FILE_PATTERNS *.h)
+set(DOXYGEN_FILE_PATTERNS *.h *.md)
 set(DOXYGEN_GENERATE_TREEVIEW YES)
 set(DOXYGEN_HIDE_FRIEND_COMPOUNDS YES)
 set(DOXYGEN_HIDE_IN_BODY_DOCS YES)
 set(DOXYGEN_HIDE_UNDOC_CLASSES YES)
 set(DOXYGEN_HIDE_UNDOC_MEMBERS YES)
 set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
+set(DOXYGEN_MARKDOWN_ID_STYLE GITHUB)
 set(DOXYGEN_QT_AUTOBRIEF YES)
 set(DOXYGEN_QUIET YES)
 set(DOXYGEN_RECURSIVE YES)
@@ -27,8 +29,6 @@ set(DOXYGEN_SORT_MEMBER_DOCS NO)
 set(DOXYGEN_SOURCE_BROWSER YES)
 set(DOXYGEN_STRIP_CODE_COMMENTS NO)
 
-doxygen_add_docs(doc
-                 "${Halide_SOURCE_DIR}/src"
-                 "${Halide_SOURCE_DIR}/test"
-                 ALL
+doxygen_add_docs(doc "doc/" "src/" "test/" ALL
+                 WORKING_DIRECTORY "${Halide_SOURCE_DIR}"
                  COMMENT "Generate HTML documentation")

doc/HalideCMakePackage.md

@@ -532,9 +532,9 @@ will be added to the extension as a callable method of the module. Note that
 every library specified must be built with the `PYTHON_EXTENSION` keyword
 specified, and all libraries must use the same Halide runtime.
 
-The result will be a shared library of the form
-`<target>.<soabi>.so`, where <soabi> describes the specific Python version and
-platform (e.g., `cpython-310-darwin` for Python 3.10 on macOS.)
+The result will be a shared library of the form `<target>.<soabi>.so`, where 
+`<soabi>` describes the specific Python version and platform (e.g., 
+`cpython-310-darwin` for Python 3.10 on macOS.)
 
 ### `add_halide_runtime`
 

doc/Python.md

@@ -11,7 +11,7 @@
   * [Example of Simple Usage](#example-of-simple-usage)
   * [Halide Generators In Python](#halide-generators-in-python)
     * [Writing a Generator in Python](#writing-a-generator-in-python)
-      * [@hl.generator("name")](#hlgeneratorname)
+      * [`hl.generator("name")`](#hlgeneratorname)
       * [hl.GeneratorParam](#hlgeneratorparam)
       * [hl.InputBuffer, hl.InputScalar](#hlinputbuffer-hlinputscalar)
       * [hl.OutputBuffer, hl.OutputScalar](#hloutputbuffer-hloutputscalar)
@@ -348,7 +348,7 @@ C++ Generators for the following to make sense.)
 
 Let's take the details here one at a time.
 
-#### @hl.generator("name")
+#### `hl.generator("name")`
 
 This decorator adds appropriate "glue" machinery to the class to enforce various
 invariants. It also serves as the declares a "registered name" for the
@@ -523,9 +523,9 @@ add_halide_python_extension_library(my_extension
 This compiles the Generator code in `logical_op_generator.py` with the
 registered name `logical_op_generator` to produce the target `xor_filter`, and
 then wraps the compiled output with a Python extension. The result will be a
-shared library of the form
-`<target>.<soabi>.so`, where <soabi> describes the specific Python version and
-platform (e.g., `cpython-310-darwin` for Python 3.10 on OSX.)
+shared library of the form `<target>.<soabi>.so`, where `<soabi>` describes 
+the specific Python version and platform (e.g., `cpython-310-darwin` for 
+Python 3.10 on OSX.)
 
 Note that you can combine multiple Halide libraries into a single Python module;
 this is convenient for packaging, but also because all the libraries in a single