Separation of proposals and Specification

[marty-johnson59]

Moving this issue over from the archived Antora repo (https://gitlab.khronos.org/vulkan/antora/-/issues/6 per @Tobski)

Currently the docs website has the proposals lumped under the spec documentation, and it's kind of a weird place for them as they're all sitting at the end as a long collapsed list of extensions.
IMO it would be good to have these separated out to a separate page so they can be found more prominently. We may also want to consider how they're labelled - something like "Feature Overviews" would be a useful direction to move in I think.

[oddhack]

We can, fairly easily, make the proposals into a separate Antora component like the Guide and Tutorial are. They will necc. appear as separate pages. It's a reasonable way of doing it - there are many options with Antora that are essentially aesthetic preferences / beliefs about how the site will be used. Antora is a static site generator, we can't refactor on the fly to present two sets of pages as two components vs. one component. So we have to choose, and whatever choices we make will be suboptimal for some uses.

[oddhack]

We will give this a try - @oddhack will make appropriate changes in the spec preprocessing script and Antora build script.

[oddhack]

Fixed link to internal gitlab site.

[oddhack]

@Tobski this has been done and docs.vulkan.org updated. The (renamed) "Feature Descriptions" component appears in the lower-left nav. There are probably some dangling naming changes in spec text but the internal links and cross-links (such as the link from https://docs.vulkan.org/spec/latest/appendices/extensions.html to the corresponding feature description) seem OK. We probably want to address the "proposal" / "feature description" dichotomy - maybe call them "proposed feature descriptions" while in development or something like that. If you see problems, please open a new issue.

[Tobski]

I didn't even realise there was a lower left nav, would be good to get a link in the upper bar, but we can treat that as a separate issue if that's preferable? Everything else in the lower left nav seems to be duplicated in the upper bar, so I'm not sure of its purpose other than now this.

[oddhack]

I didn't even realise there was a lower left nav, would be good to get a link in the upper bar, but we can treat that as a separate issue if that's preferable? Everything else in the lower left nav seems to be duplicated in the upper bar, so I'm not sure of its purpose other than now this.

The lower-left nav is autogenerated from the Antora component descriptions. The top nav is hand-edited HTML in the site UI bundle (and is particularly annoying because you can't use Antora navigation descriptors, you have to find the actual relative URL of anything in the site you're linking to). But sure, the feature descriptions could go up there as well. Probably under the "Education" menu?