Major ApolloServer API reference edits for new reference proof of concept

[StephenBarlow]

No description provided.

[StephenBarlow]

@abernix This is ready for content review and merge-if-correct on my end if it is on yours

[glasser]

I think it might look nice to merge the name and type into one column with two lines, to give more horizontal space to the description. In general I think the table makes it a lot easier to browse the page!

[StephenBarlow]

Now awaiting some small style changes to the docs theme to support a two-column field table per comment above

[glasser]

I think you lost these?

Personally I don't mind if we pretend tracing doesn't exist. I'm pretty sure people do need to set the cacheControl options like defaultMaxAge pretty frequently though.

[abernix]

This is a huge improvement, both in terms of the improved phrasing of all too many things to mention and in terms of the visual treatment.

The only thing I had worth pointing out was that there was still some horizontal scrolling — even on Desktop viewports — happening due to the width of the Engine Reporting Options section, but @glasser already noted that and you've indicated some theme changes are forthcoming.

As another point worth mentioning, but of which I'm not asking for a solution, I find the overall syntax for building this page a bit hard to grok and I worry that it may be hard for contributors to be comfortable with. This is in a large part due to, e.g., ### headings within <td> tags and the tag-based nature of HTML (i.e., needing to track tags along with markdown at the same time).

I don't have any concrete suggestions on how to fix that right now, but since we already have YAML front-matter, perhaps a combination of markdown and YAML is another way the documentation could be defined? For example, a YAML structure which defines that we are an API-table-based dealie (and automatically applying the various heading/table treatments, defining the data declaratively in that format, while still supporting markdown within it.

This seems like a proprietary format that I'm describing, but maybe something already exists?

Anyhow, just some thoughts, but thanks so much for applying this! I look forward to seeing the theme adjustments prior to merging, but for now this is a tentative ✅ LGTM.

[glasser]

FWIW I agree that the formatting is a big pain, but also that the readability improvements are worth it. Certainly if there's something else with a nice build step to make it more maintainable that would be cool too!

[StephenBarlow]

@abernix Thanks for reviewing, and for your feedback on the formatting! I agree that the structure of this table is currently more complex than it should be, and we should find a way of hiding that complexity from authors. With front-end priorities elsewhere at the moment, I think we should proceed with this for now, and subsequent transformations will hopefully be comparatively lightweight.

The new two-column formatting can now be seen here: https://deploy-preview-4494--apollo-server-docs.netlify.app/docs/apollo-server/api/apollo-server/

To the issue with horizontal scroll, I've resolved that for now by simply reverting the EngineReportingOptions table to the previous list format, since it's going away in a few days anyway.

Once this is merged as a proof of concept, I'll start applying the same treatment to the balance of the API reference over the next week or two.

[abernix]

This looks amazing. I've applied two extra commits that appear to have gone astray and with them back in their rightful home in this beautiful new API treatment, I think we're good to go. ✅

Thank you so much for your work on this!