Visual and structural improvements to docs generator HTML #4755

straight-shoota · 2017-07-28T17:01:58Z

This adds the following improvements to the docs generator:

Structural

renamed partial templates with leading underscore to distinguish them from page templates
combined shared code for <head> into partial _head.html partial (DRY up)
combined shared code for sidebar into partial _sidebar.html (DRY up)
replaced element IDs for CSS selectors with classes to reduce specifity in stylesheets (avoid specifity wars)
replaced absolute position with flexbox
added .sidebar-header element (which currently includes .search-box)

Visual

added CSS class .source-link with improved visual style to source links
~~changed default font to Roboto~~
~~added Montserrat as accent font~~
added a:hover indicator
increased border for h2
limited width for content elements (p, pre) to 55 em for improved legibility
added a slight background and border for inline code elements
added a slight visual separation between .sidebar-header and .types-list

Fonts

Font changes have been removed from this PR to be discussed in #5053
The API docs should use Crystal's CD font Roboto as specified on https://crystal-lang.org/media/ to have a similar visual style as other Crystal resources. The previous default Avenir is not openly available and fallbacks Tahoma, Lucida Sans and Lucida Grande don't look very nice.
Better alternative fonts are Muli and Lato whith a similar appearance to Avenir, so I added them as fallbacks, too.

~~Montserrat looks nice with Roboto for headlines and other accented styles.~~

All added fonts are available on Google Fonts, though only the defaults
Roboto and Montesrrat are loaded through the stylesheet.

Preview

LIVE PREVIEW

README with fonts and h2 border-bottom:

Sample with fonts, code background and limited line length:

Sample with source link and limited line length:

straight-shoota · 2017-07-30T11:23:24Z

I've added a .sidebar-header element (which currently includes .search-box) which makes the search box stand out a bit from the results list. This would also be a good spot for name, version and date of the documented API as suggested in #4754

The live preview shows the current state.

There is also an enhanced search interface based on this PR and #4746. I'd like to get this or the other merged so I can rebase accordingly and keep a simple commit history.

oprypin · 2017-08-14T21:49:08Z

Good job! Can't wait for this

There is also an enhanced search interface based on this PR and #4746. I'd like to get this or the other merged so I can rebase accordingly and keep a simple commit history.

I am against using web fonts. Keep it lightweight.

oprypin · 2017-08-14T21:53:35Z

Inline code looks weird.
Compare Overview in old/new

oprypin · 2017-08-14T21:55:46Z

There is way too much spacing added in the sidebar, both regarding the width and line spacing. I'd say the spacing is too much even as it is right now.

straight-shoota · 2017-08-14T22:36:15Z

Thanks for your remarks @oprypin, I'll address your comments in one:

Web fonts don't add much overhead, it just needs to be downloaded once. From a technical point this is negligible considering the API docs are usually browsed relatively frequently. It is rather a question of visual style: should there be a unique look everywhere (which requires to provide font definitions) or more variation and usage of system-specific fonts (this is used for the monospace fonts).
I added a slight border around inline code to highlight it against regular text. In the current style it is not always easy to distinguish. Although I believe I added this before I changed the fonts, and Roboto and Consolas have a higher contrast than Avenir and Consolas. If we keep this fonts it might be okay to remove the border, but that also depends on the other monospace fonts.
The paddings there did not change. I think this entire type list needs some review in a dedicated topic, There are some usability issues in the way this is implemented and it might be worth rethinking navigation overall. There have been a few comments and ideas about that in the past.

oprypin · 2017-08-14T22:48:31Z

Here's what I see.

Can't agree with "paddings there did not change". We don't need to discuss the sidebar's general problems to see that something is off.

straight-shoota · 2017-08-14T22:59:53Z

Tahoma on the left (which is the current default if Avenir is not available) has much bigger letters than Roboto on the right, even at the same font-size. The paddings are exactly the same, it's just that the letters on the right are smaller and therefore increase the impression of space around the text.

oprypin · 2017-08-14T23:02:40Z

Do you not see that the picture on the right has a wider sidebar and also fits in less text vertically? They are taken at the exact same scale and viewport size

oprypin · 2017-08-14T23:08:11Z

Mobile before/after ☹️

RX14 · 2017-08-15T10:28:31Z

You should set the list vertical padding to 0 and use line-height: 1.5 for the list.
Web fonts are fine as long as there's a defined fallback which also looks good.
Mobile in general needs the sidebar to be toggleable.

straight-shoota · 2017-08-15T10:58:45Z

@oprypin Oh yes, the width of the sidebar changed slightly but this has nothing to do with paddings. Before, it was a relative value (20% of viewport width) and I changed it to an absolute 30em which makes more sense in general, considering that the viewport could be very large or very small but the sidebar should always be about the same width. This could be further improved by making the width slightly responsive.

Mobile sucks before and after. I have a few improvements for that (including toggleable sidebar) but I'd address this in another PR because this one is already quite extensive and tweaking a responsive layout can be challenging by itself. I'd prefer to get this merged as the standard layout for "normal size" screens and then work on improving other sizes.
I guess I should remove the viewport meta attribute until there is proper support for smaller screens.

@RX14 I don't see any benefit in using line-height over vertical padding. There shouldn't be any line breaks inside a type list item, so there shouldn't be any difference. But if there would be one by any chance, it's better to have the space between items defined as padding instead of line-height.
You proposed values lead to misplaced triangles (tree node symbols), so this would need some adjustments. But I'd prefer not to touch the specifics of the type list style in this PR because this might need to be reworked anyway.

RX14 · 2017-08-15T11:19:13Z

@straight-shoota the benefit of line-height is that it's relative to the font size. Just replacing .types-list a with line-height: 1.5; padding-left: 30px makes the left arrows more central. At least in firefox.

straight-shoota · 2017-08-15T11:44:27Z

@RX14 I guess that depends on your defaults. The triangle element a::before has a fixed height of 30px. A font-size of 16px (that's the default value in my Chrome installation) with line-height: 1.5 results in the total height of the anchor element at 24px - which means a misaligned triangle. With a default line-height of (usually) 1.2 the line height is 19.2px and with two 5px paddings it adds up to about 30px total height - which makes the triangles fit.
So yes, this whole type list needs a big overhaul but also requires a discussion about the usability features (among others).

vladfaust · 2017-09-23T18:49:33Z

I'm usually very tolerant to design updates if they aim to minimalism and efficiency. But in this case I strongly dislike new fonts. They are much harder to read. Regarding to headers, it feels like serif font. I vote for Roboto! 👊

akzhan · 2017-09-23T22:50:46Z

What about separate pull requests?

I want all of this except fonts.

Fonts may be subject of another PR.

straight-shoota · 2017-09-27T10:05:28Z

Sure, I can easily extract the fonts to discuss them separately. Though I'd like to hear what others (especially core members) think first.

ysbaddaden · 2017-09-27T13:28:47Z

First of all, the structural changes are very welcome. It follows overall good practices and cleans things up 👍

I'm not fond of visual changes. The bolder view-source link is attracting the attention too much and isn't very pretty. The new fonts may follow the Crystal branding, but this isn't a crystal branding website, this is a reference. We should focus on readability, try to fit better with the gitbook documentation maybe, not impose Crystal branding to the documentation of each and every project.

To be honest, I don't like the actual fonts either. I wish we used a mere helvetica, sans-serif and consolas, monospace, instead of that huge list of font families. I wish we improved typography with a line-height: 1.4 too. Best rendering, best readability to my taste.

Also, the actual sidebar behaves better on smaller screen than yours. I'm not talking of smartphones screens, but half of my 15" laptop screen for example: yours takes too much space, at the expense of the documentation.

straight-shoota · 2017-09-27T13:44:52Z

Thanks for the feedback!

I'll try modify the source links to make them stand out less. Maybe some lighter color and smaller font-size can do this or a lighter font size.
I think it's best to discuss fonts in a separate issue. I was pretty confident that everyone would agree to follow the Crystal CI but obviously this is not the case ;)
Half a 15" laptop screen is actually about the size of a smartphone and we need a solid solution for these sizes anyway: Neither the current nor my proposal are very usable. I'll add a max-width: 20% to reduce the width on smaller viewport sizes until there is a proper solution.

ysbaddaden · 2017-09-27T14:48:06Z

No. Half of my 15" inch laptop screen is bigger than my 9.7" iPad. It's a lot bigger than my 5" smartphone !

straight-shoota · 2017-09-28T11:47:10Z

@ysbaddaden I wasn't talking about physical dimensions but visually perceived size. A typical 15" laptop screen fits about 80 to 85em horizontal, a smartphone or tablet usually somewhere between 50 and 60em. So half a 15" screen actually fits less characters per line than a 5" smartphone in default font size.

I have removed the font changes from this PR and opened #5053
Small-screen display has been improved (basically to be similar as it was before this PR) and the source links have been downsized.
The preview link now contains the updated changes.

* adds a:hover indicator * increased border for h2 * limited width for content elements (p, pre) to 55 em for improved legibility * adds a slight background and border for inline code elements

This dries up sidebar code. Element IDs for CSS selectors are replaced with classes to reduce specifity in stylesheets (avoid specifity wars). Flexbox is better than absolute positioning as it allows for more flexible layout and dimensions.

temporary workaround

chances · 2021-12-16T00:22:55Z

@straight-shoota Is this PR dead in the water?

The search input's placeholder text is not accessible as-is, according to the W3C's WCAG specification:

Using this CSS resolves the issue:

.sidebar input::placeholder {
    color: black;
    font-size: 14px;
    text-indent: 2px;
}

straight-shoota · 2021-12-16T11:05:41Z

Is this PR dead in the water?

Pretty much, yes. Most of the proposed changes have been applied in separate PRs. Not even sure what else is left to do. So I guess it's time to close this. We can alwas cherry pick items from here.

Please open a new PR for the placeholder text.

chances · 2021-12-17T00:23:30Z

Okay, I've opened #11604.

straight-shoota added a commit to straight-shoota/crystal that referenced this pull request Jul 30, 2017

Add preview for doc improvements crystal-lang#4755

f75f3db

straight-shoota added a commit to straight-shoota/crystal that referenced this pull request Jul 30, 2017

Add preview for doc improvements crystal-lang#4755

5edc8db

straight-shoota added a commit to straight-shoota/crystal that referenced this pull request Jul 30, 2017

Add preview for doc improvements crystal-lang#4755

ed82016

straight-shoota force-pushed the jm-docs-improvements branch from 54d24d4 to 0641a4f Compare September 28, 2017 10:43

straight-shoota mentioned this pull request Sep 28, 2017

Fonts for API docs #5053

Closed

straight-shoota force-pushed the jm-docs-improvements branch from 0641a4f to e830275 Compare October 11, 2017 10:14

straight-shoota force-pushed the jm-docs-improvements branch from e830275 to 0641a4f Compare November 1, 2017 11:50

straight-shoota added 3 commits November 1, 2017 12:53

Rename partial templates with leading underscore

0074d4a

Add .source-link style

4888a5f

Add _head.html partial to dry up html head

9d7aa27

straight-shoota added 3 commits November 1, 2017 12:53

Visual improvements:

8be4c57

* adds a:hover indicator * increased border for h2 * limited width for content elements (p, pre) to 55 em for improved legibility * adds a slight background and border for inline code elements

Fix visual appearance for type-list links

b0f1f46

straight-shoota force-pushed the jm-docs-improvements branch 2 times, most recently from 601df5b to 666efe0 Compare November 1, 2017 13:08

straight-shoota mentioned this pull request Nov 1, 2017

Improved search feature for API docs #5229

Merged

straight-shoota added 5 commits November 1, 2017 21:13

Add sidebar-header with slight visual distance from types-list

3f4118f

Improve layout for smaller screen sizes

8d6f8bb

temporary workaround

Reduce visual impact of .source-link

db1ad01

Add title to .source-link

d3fd44c

Use monospace for .superclass separator

01f7e08

straight-shoota force-pushed the jm-docs-improvements branch from 666efe0 to 01f7e08 Compare November 1, 2017 20:14

This was referenced Mar 9, 2018

Add highlight to code tag in generated API docs #5795

Merged

Refactor docs generator HTML scaffold #5816

Merged

straight-shoota mentioned this pull request Apr 11, 2018

Crystal API docs sidebar bad README indentation #5940

Closed

faustinoaq mentioned this pull request Jun 19, 2018

Create Documentation, Guides and API amberframework/amberframework.org#3

Closed

3 tasks

straight-shoota added kind:feature topic:tools:docs-generator labels Feb 7, 2020

straight-shoota closed this Dec 16, 2021

straight-shoota deleted the jm-docs-improvements branch January 10, 2023 19:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Visual and structural improvements to docs generator HTML #4755

Visual and structural improvements to docs generator HTML #4755

straight-shoota commented Jul 28, 2017 •

edited

Loading

straight-shoota commented Jul 30, 2017 •

edited

Loading

oprypin commented Aug 14, 2017

oprypin commented Aug 14, 2017

oprypin commented Aug 14, 2017

straight-shoota commented Aug 14, 2017 •

edited

Loading

oprypin commented Aug 14, 2017

straight-shoota commented Aug 14, 2017

oprypin commented Aug 14, 2017

oprypin commented Aug 14, 2017

RX14 commented Aug 15, 2017 •

edited

Loading

straight-shoota commented Aug 15, 2017 •

edited

Loading

RX14 commented Aug 15, 2017

straight-shoota commented Aug 15, 2017 •

edited

Loading

vladfaust commented Sep 23, 2017 •

edited

Loading

akzhan commented Sep 23, 2017

straight-shoota commented Sep 27, 2017

ysbaddaden commented Sep 27, 2017 •

edited

Loading

straight-shoota commented Sep 27, 2017

ysbaddaden commented Sep 27, 2017

straight-shoota commented Sep 28, 2017

chances commented Dec 16, 2021 •

edited

Loading

straight-shoota commented Dec 16, 2021

chances commented Dec 17, 2021

Visual and structural improvements to docs generator HTML #4755

Visual and structural improvements to docs generator HTML #4755

Conversation

straight-shoota commented Jul 28, 2017 • edited Loading

Fonts

Preview

straight-shoota commented Jul 30, 2017 • edited Loading

oprypin commented Aug 14, 2017

oprypin commented Aug 14, 2017

oprypin commented Aug 14, 2017

straight-shoota commented Aug 14, 2017 • edited Loading

oprypin commented Aug 14, 2017

straight-shoota commented Aug 14, 2017

oprypin commented Aug 14, 2017

oprypin commented Aug 14, 2017

RX14 commented Aug 15, 2017 • edited Loading

straight-shoota commented Aug 15, 2017 • edited Loading

RX14 commented Aug 15, 2017

straight-shoota commented Aug 15, 2017 • edited Loading

vladfaust commented Sep 23, 2017 • edited Loading

akzhan commented Sep 23, 2017

straight-shoota commented Sep 27, 2017

ysbaddaden commented Sep 27, 2017 • edited Loading

straight-shoota commented Sep 27, 2017

ysbaddaden commented Sep 27, 2017

straight-shoota commented Sep 28, 2017

chances commented Dec 16, 2021 • edited Loading

straight-shoota commented Dec 16, 2021

chances commented Dec 17, 2021

straight-shoota commented Jul 28, 2017 •

edited

Loading

straight-shoota commented Jul 30, 2017 •

edited

Loading

straight-shoota commented Aug 14, 2017 •

edited

Loading

RX14 commented Aug 15, 2017 •

edited

Loading

straight-shoota commented Aug 15, 2017 •

edited

Loading

straight-shoota commented Aug 15, 2017 •

edited

Loading

vladfaust commented Sep 23, 2017 •

edited

Loading

ysbaddaden commented Sep 27, 2017 •

edited

Loading

chances commented Dec 16, 2021 •

edited

Loading