Design suggestion for generated docs #3429
Conversation
|
I played with this a bit. The improvements to light mode look nice. Here are 2 issues I found:
The underscore is hidden by the hyperlink here.
The error names and descriptions layout is jumbled here. I'd be happy to merge this if the above things are fixed and:
|
andrewrk
added
the
work in progress
|
@andrewrk page for readFileAlloc is empty in |
Additionally introduces css variables
you'll want to use the |
|
Ready for review |
andrewrk
removed
the
work in progress
There was a problem hiding this comment.
I apologize, the reason I've been putting off merging this PR so far is that you're using all these advanced CSS things that I've never seen before, which is cool, but I want to make sure that we can rely on these features being widely available. I'm willing to do the work of figuring this stuff out on my own, but if you're willing to hold my hand a little bit it would expedite the merging process.
| body { | ||
| font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif; | ||
| max-width: 60em; | ||
| :root { |
There was a problem hiding this comment.
I don't recognize this CSS feature. What is it called, and is it supported everywhere?
There was a problem hiding this comment.
Its "root element selector", it overrides html selector.
Chrome 1+, Firefox 1+, Safari 1+.
| max-width: 60em; | ||
| :root { | ||
| font-size: 1em; | ||
| --ui: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; |
There was a problem hiding this comment.
Same here, what's with the -- ?
There was a problem hiding this comment.
These are "css custom properties" aka "css variables".
Chrome 49+, Firefox 31+, Safari 9+.
IE no support at all.
| overflow: hidden; | ||
| margin: 0; | ||
| padding: 0; | ||
| font-family: var(--ui); |
There was a problem hiding this comment.
same thing here. I'm worried about widespread compatibility. Is this available everywhere?
There was a problem hiding this comment.
Same here - css variables.
| overflow-x: auto; | ||
|
|
||
| .flex-main { | ||
| display: flex; |
There was a problem hiding this comment.
Flexbox works in Chrome 29+, Safari 9+ and in Firefox since v20 with some minor bugs (for advanced stuff).
| height: 100vh; | ||
|
|
||
| .flex-left { | ||
| width: 12rem; |
There was a problem hiding this comment.
"root" em. Not affected by changing target element's font-size.
Chrome 4+, Firefox 3.6+, Safari 5+.
| box-shadow: 0 0.3em 1em 0.125em var(--search-sh-color); | ||
| } | ||
|
|
||
| .docs .search::placeholder { |
There was a problem hiding this comment.
Pseudo-element selector that allows to apply styles to <input>'s placeholder attribute (its not affected by other means and does not inherit from <input>).
Chrome 57+, Firefox 51+, Safari 10+.
(Should be silently ignored if not supported)
|
Thanks for walking me through this stuff! I'll take one more peek at it and then press that big green button :) |
|
Looks great! Thanks! |
|
What can be done next to improve generated docs? Should it be optimised for mobile or PC is enough? |
|
Here are some related issues:
And finally, multibuilds. Multibuilds is a big topic, but as far as std lib documentation for the near term, I'm in the middle of implementing a tool in zig that merges multiple semantic analysis dumps into one, which will make the std lib documentation aware of multiple targets rather than only the one active during documentation generation. I would like to note that this semantic analysis dump also paves the way for third party integrations, for example the language server protocol. I don't plan on doing any work on this until the self-hosted compiler, but if any community members are interested in taking a stab at it, there is now a nice big juicy JSON formatted dump of all the semantic analysis the compiler has done, and pretty straightforward JavaScript code showing you how to take advantage of it. |
I played with styles and made this draft. Dark mode is broken at the moment.