feat(ruby): display friendly api name before page title for Ruby docs #367

dansaadati · 2022-04-04T22:14:06Z

This change modifies the template to prepend the "friendlyApiName" in the <h1> of generated pages. This also updates the Ruby test yaml and accompanying golden doc set.

dandhlee

Could you remove the unnecessary files? For the purpose of showing the friendly title, YAML updates are fine but it's containing a bit more than we should need for this PR, making it harder to focus on the necessary changes.

dandhlee · 2022-04-04T23:27:38Z

third_party/docfx/templates/devsite/UniversalReference.html.primary.js

@@ -13,6 +13,7 @@ exports.transform = function (model) {
  }

  model._disableToc = model._disableToc || !model._tocPath || (model._navPath === model._tocPath);
+  model._displayFriendlyApiName = model._displayFriendlyApiName && model.friendlyApiName


Since we already have {{#_displayFriendlyApiName}} in the template, this is a redundant check.

This checks that the friendlyApiName key in the yaml present and non-empty.

Right, do we need to check that it's present and non-empty for a specific reason? Suppose that this JavaScript line isn't there, if _displayFriendlyApiName is not present then the template will not render it. That's why I think this is a redundant check, unless there's a reason I'm not aware of.

There's a - character between the friendly api name and the existing title. If the friendlyApiName key is missing from the yaml, the dash character will still appear unless we have this additional condition.

dansaadati · 2022-04-05T17:43:33Z

Could you remove the unnecessary files? For the purpose of showing the friendly title, YAML updates are fine but it's containing a bit more than we should need for this PR, making it harder to focus on the necessary changes.

Yes, we can do the updates to the Ruby yaml and golden doc set as a follow-up.

…gleapis/doc-templates into title-with-friendly-api-name

dandhlee

Could you update the goldens? Looks like the slight changes triggered whitespace changes, curious how it look snow.

…gleapis/doc-templates into title-with-friendly-api-name

tbpg · 2022-04-06T12:41:01Z

third_party/docfx/templates/devsite/UniversalReference.html.primary.tmpl

@@ -1,7 +1,10 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
 {{!master(layout/_master.tmpl)}}

-<h1 class="page-title">{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}}</h1>
+<h1 class="page-title">
+{{#_displayFriendlyApiName}}


I don't think we need _displayFriendlyApiName. Values are truthy in the template. So, we should just be able to do

{{#friendlyApiName}} {{friendlyApiName}} {{/friendlyApiName}}

I was hoping to have a flag, _displayFriendlyApiName, to either enable or disable this change from doc-pipeline. Ruby libraries are already generating yaml with the friendlyApiName key so updating the template would effectively make this change live on prod for at least some Ruby libraries. However, I think just relying on the friendlyApiName key (and not changing the docfx JSON) is okay too as this is a pretty safe change. Wdyt?

To disable this experiment, we can remove this from the template, or "turn off" them on docfx.json. At the moment because there is no experiment structure they're equivalent (as in a PR for deleting/changing in this repo). In that case I'd prefer to have the template only contain what's necessary rather than leaving this behind and possibly forgetting this later on.

That's a good point, we can just use the friendlyApiName key directly then.

dandhlee

LGTM.

tbpg · 2022-04-07T16:26:11Z

testdata/goldens/go/index.html

@@ -8,7 +8,9 @@
    {% verbatim %}
    <div>
      <article data-uid="cloud.google.com/go/storage">
-<h1 class="page-title">Package cloud.google.com/go/storage
+<h1 class="page-title">


Any way we can avoid these whitespace changes? This would modify every file. Would be nice not to. Fine if not.

Yes, if we keep it all in one line in the template, but it's slightly less readable:

<h1 class="page-title">{{#friendlyApiName}}{{friendlyApiName}} - {{/friendlyApiName}}{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}}</h1>

Wdyt?

That is pretty intense to read. So, let's leave it as-is.

* factor out setting property type * factor out property type name from ManagedReference pre-renderer * remove dependency on partials/title * modify to access first element in name * edit title in common.js based on type * chore: write title in preprocessor instead of partial template * fix minor bugs, add new line on </h1> to match golden * fix: use model type instead of javaType, loosen title restriction in template * fix: remove newline in <h1>, document getTitleForTypeProperty function Co-authored-by: Dan Lee <[email protected]>

dansaadati requested a review from a team April 4, 2022 22:14

dansaadati added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Apr 4, 2022

kokoro-team removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Apr 4, 2022

dansaadati assigned tbpg Apr 4, 2022

dandhlee suggested changes Apr 4, 2022

View reviewed changes

feat(ruby): add friendly api name to page title

99f2b83

dansaadati force-pushed the title-with-friendly-api-name branch from d44ce1c to 99f2b83 Compare April 5, 2022 17:38

dansaadati requested a review from dandhlee April 5, 2022 17:43

dansaadati unassigned tbpg Apr 5, 2022

dansaadati added 2 commits April 5, 2022 14:03

feat(ruby): add friendly api name to page title

914c36b

Merge branch 'title-with-friendly-api-name' of https://github.com/goo…

8fb693a

…gleapis/doc-templates into title-with-friendly-api-name

dandhlee suggested changes Apr 5, 2022

View reviewed changes

dansaadati added 2 commits April 5, 2022 15:50

Merge branch 'title-with-friendly-api-name' of https://github.com/goo…

481a153

…gleapis/doc-templates into title-with-friendly-api-name

Merge branch 'title-with-friendly-api-name' of https://github.com/goo…

a11becb

…gleapis/doc-templates into title-with-friendly-api-name

tbpg suggested changes Apr 6, 2022

View reviewed changes

dandhlee and others added 2 commits April 6, 2022 21:04

chore(deps): update dependency click and black together (#365)

daa5d46

chore(deps): update dependency protobuf to ~=3.20.0 (#366)

709c853

dansaadati requested a review from tbpg April 6, 2022 22:28

dansaadati force-pushed the title-with-friendly-api-name branch from c0eb7a3 to 569f0cc Compare April 7, 2022 16:11

feat(ruby): add friendly api name to page title

d7470a6

dansaadati force-pushed the title-with-friendly-api-name branch from 569f0cc to d7470a6 Compare April 7, 2022 16:15

dansaadati requested a review from dandhlee April 7, 2022 16:18

Merge branch 'main' into title-with-friendly-api-name

c77894a

dandhlee approved these changes Apr 7, 2022

View reviewed changes

tbpg approved these changes Apr 7, 2022

View reviewed changes

renovate-bot and others added 4 commits April 13, 2022 15:50

chore(deps): update dependency google-cloud-core to ~=2.3.0 (#371)

8181f80

feat(ruby): add friendly api name to page title

1746065

dansaadati and others added 5 commits April 13, 2022 15:54

feat(ruby): add friendly api name to page title

f4446c5

feat(ruby): add friendly api name to page title

45a7ad7

fix: update goldens to match newline remove on </h1>

21defef

Merge branch 'main' into title-with-friendly-api-name

205c633

fix: remove extra line in template

0431dc1

dansaadati mentioned this pull request Apr 14, 2022

feat(Ruby): add intro sentence to summary with friendly api name #373

Merged

dansaadati mentioned this pull request Apr 27, 2022

feat(godocfx): add friendly api name to yaml googleapis/google-cloud-go#5949

Closed

Merge branch 'main' into title-with-friendly-api-name

5d2738a

dansaadati merged commit 7fb7d91 into main Apr 27, 2022

dansaadati deleted the title-with-friendly-api-name branch April 27, 2022 22:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ruby): display friendly api name before page title for Ruby docs #367

feat(ruby): display friendly api name before page title for Ruby docs #367

dansaadati commented Apr 4, 2022 •

edited

Loading

dandhlee left a comment

dandhlee Apr 4, 2022

dansaadati Apr 5, 2022

dandhlee Apr 5, 2022

dansaadati Apr 5, 2022

dansaadati commented Apr 5, 2022

dandhlee left a comment

tbpg Apr 6, 2022

dansaadati Apr 6, 2022

dandhlee Apr 7, 2022

dansaadati Apr 7, 2022

dandhlee left a comment

tbpg Apr 7, 2022

dansaadati Apr 7, 2022

tbpg Apr 7, 2022

feat(ruby): display friendly api name before page title for Ruby docs #367

feat(ruby): display friendly api name before page title for Ruby docs #367

Conversation

dansaadati commented Apr 4, 2022 • edited Loading

dandhlee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dansaadati commented Apr 5, 2022

dandhlee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dandhlee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dansaadati commented Apr 4, 2022 •

edited

Loading