[DOCS] Bring back Doxygen based reference for SYCL after PR #15483

[hfp]

Is your feature request related to a problem? Please describe

The Doxygen based reference disappeared after PR #15483 and public URLs and indexed pages yield a 404.

Describe the solution you would like

The new documentation at https://intel.github.io/llvm/ looks more like regular LLVM documentation pages. However, the Doxygen based pages were used like a class reference and had no other documentation matching this content (incl. Intel specific extensions).

Describe alternatives you have considered

The referred PR also changed the kind of content away from reference documentation. Please make a browsable reference available again. For SYCL, the Doxygen based documentation is useful and avoids to fiddle around with header files directly.

Additional context

No response

[bader]

However, the Doxygen based pages were used like a class reference and had no other documentation matching this content (incl. Intel specific extensions).

I'd like to challenge this statement. Public API is described in the SYCL specification and Intel specific extensions are described here: https://github.com/intel/llvm/tree/sycl/sycl/doc/extensions.

[hfp]

What's the worry about an automatically generated documentation? I recommend to fix at least the 404's and forward to the new documentation. Even if that same info can be found elsewhere (Doxygen like reference), isn't this just an advantage for a mighty programming model?

[hfp]

To give an example of why I am missing the Doxygen documentation: I was looking for reference information about make_context and make_queue of course not knowing the exact function names but rather "it's related to the backend class template". Entering https://intel.github.io/llvm/, I have a hard time to get close to any such information or an entry point since it's no reference but a topic-oriented documentation.

[0x12CC]

@hfp, I'm not familiar with the Doxygen documentation you mentioned and wasn't able to find an archived version in older commits. Is the information you're looking for different from what's available here?

[bader]

To give an example of why I am missing the Doxygen documentation: I was looking for reference information about make_context and make_queue of course not knowing the exact function names but rather "it's related to the backend class template". Entering https://intel.github.io/llvm/, I have a hard time to get close to any such information or an entry point since it's no reference but a topic-oriented documentation.

I agree with @0x12CC that it's better to use SYCL specification to find SYCL API you can use in the application. The API generated by the Doxygen includes internal API, which can be changed any time. Please, let us know if you have any issues with using SYCL specification.

[hfp]

Fine with me when looking at 4.5.1.3. Template functions make_*.

I can see the point of looking at a spec rather than documentation derived from an internal source base or an implementation specific to a vendor.

Still, old URLs may want to forward to the new location (there is value with things that worked previously). There should be little ambition to de-duplicate the world especially for the "newcomer"...

[bader]

Still, old URLs may want to forward to the new location (there is value with things that worked previously).

We have forwarding in place. For example, https://intel.github.io/llvm-docs/UsersManual.html is re-directed to https://intel.github.io/llvm/UsersManual.html. All pages are redirected by replacing https://intel.github.io/llvm-docs prefix to https://intel.github.io/llvm. Some old pages are mapped to non-existing pages, which return 404 error.