search

KhronosGroup / Vulkan-Site

Vulkan Documentation Project framework for integrated documentation site with spec, proposals, guide, and more
Other
25 stars 2 forks source link

Single page rendering of documentation #38

Closed ashleysmithgpu closed 1 year ago

ashleysmithgpu commented 1 year ago

Usability comment: previous documentation projects had the feature of rendering the entire spec in a single html page which I personally found extremely useful to be able to search using a browser/regex/text editor. I can't see this feature in the new rendering of the documentation. I think this may be useful for others.

oddhack commented 1 year ago

A single HTML document version of the Vulkan API spec is in the registry at https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html and we will continue to publish that. Integrating all of the site documentation besides the API spec into an even larger single document could happen if there's a clear demand for it - but just the API spec is the equivalent of thousands of PDF pages and exceedingly slow to load, which was part of the motivation for using Antora to begin with.

I believe there is an Antora extension to do this type of integration (Antora Assembler, possibly? Haven't looked into it yet.) If someone were to submit a PR with the appropriate build options to enable this output format, that would let people evaluate it.

ashleysmithgpu commented 1 year ago

As long as the existing page will continue to be published I think that should be sufficient. Maybe wait until someone else agrees that a single page would be useful to look at outputting this from Antora. Thanks for responding, appreciate it!

oddhack commented 1 year ago

Thanks - closing this then. While it may not fit your use case, we could potentially publish a zip file containing the static HTML site built by Antora, which would allow searching via regex from the command line (and maybe in an editor, if its search functionality is clever enough to span multiple files in one operation).