Skip to content

feature: ability to highlight section within (or to expand context for) a docregion #24681

New issue
New issue
Closed
Closed
feature: ability to highlight section within (or to expand context for) a docregion#24681
Labels
effort1: hoursfeatureLabel used to distinguish feature request from other issues
Milestone
docs-infra-tooling

Description

@jenniferfell
jenniferfell
opened on Jun 26, 2018

I'm submitting a...


[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[ ] Performance issue
[ ] Feature request
[X ] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead see https://github.com/angular/angular/blob/master/CONTRIBUTING.md#question
[ X] Other... Please describe: AIO infrastructure

Current behavior

docregion marks code in an example app that can be included and shown in the docs. The entire docregion is shown in the doc, with pretty-printing applied to show structure of code. There is no way to highlight the area on which you want the user to focus. Or alternatively, there is no way to include additional context around the area you want to show. All content is shown the same way.

Expected behavior

In PR #19715 @gkalpak suggested: "I think it might be useful to introduce a new feature for context in docregions that show adding to or modifying an existing file. I.e. 1-2 lines above and below the affected lines would appear grayed-out (to show what was there before the change), while the affected lines would be highlighted in color as usual."

I think that would be ideal! Configurable on a per-case basis would be super cool, but even just always grabbing 2 lines above/below and including them with a lighter font or gray background would be good. Or we could have a button and let user control "show me context" to pop open the window to show 5 lines above and below. Another option would be to let us make some code bold within a docregion (so an additional tag such as docfocus) so that it stands out within a docregion.

Minimal reproduction of the problem with instructions

What is the motivation / use case for changing the behavior?

Provide more context around a code snippet.
Highlight the area of focus within a code snippet.

Environment


Angular version: X.Y.Z


Browser:
- [ ] Chrome (desktop) version XX
- [ ] Chrome (Android) version XX
- [ ] Chrome (iOS) version XX
- [ ] Firefox version XX
- [ ] Safari (desktop) version XX
- [ ] Safari (iOS) version XX
- [ ] IE version XX
- [ ] Edge version XX
 
For Tooling issues:
- Node version: XX  
- Platform:  

Others:

Activity

  1. gkalpak commented on Jun 27, 2018

    @gkalpak
    gkalpak
    on Jun 27, 2018
    Member

    To be clear, I don't think it is possible to expand the docregion "on-demand", because docregions often come from different parts of the file and the lines that are around them do not necessarily make sense for the specific thing that the docregion is showcasing.

    What I was refering to, was the ability to specify that within a docregion, particular lines are of interest (and should be highlighted, while others are just for context (and should be grayed out or something).

    Off the top of my head, here is the proposed API:

    ...
// #docregion heroes-property
export class HeroesComponent implements OnInit {
  // #highlight-docregion heroes-property
  heroes = HEROES;
  // #endhighlight-docregion heroes-property
  // #enddocregion heroes-property
  selectedHero: Hero;

  constructor() { ... }

  ngOnInit() { ... }
// #docregion heroes-property
}
// #enddocregion heroes-property

    This would show docregion heroes-property as usual:

    export class HeroesComponent implements OnInit {
  heroes = HEROES;
  /* . . . */
}

    ...except that the heroes = HEROES line would be "highlighted" (whatever we decide this means 😁).

    So, it could look something like that (without the leading/trailing /*//, /**/ - added here for highlighting):

    /*//          export class HeroesComponent implements OnInit {          //*/
/**/            heroes = HEROES;                                        /**/
/**/            /* . . . */                                             /**/
/*//          }                                                         //*/
  2. gkalpak
    added
    featureLabel used to distinguish feature request from other issues
    effort1: hours
    comp: docs-infra
    on Jun 27, 2018
  3. ngbot
    added this to the Backlog milestone on Jun 27, 2018
  4. jenniferfell
    added
    subtype: docs-design
    on Sep 13, 2018

  5. jenniferfell commented on Dec 20, 2018

    @jenniferfell
    jenniferfell
    on Dec 20, 2018
    ContributorAuthor

    @StephenFluin @brandonroberts FYI...this is the open issue I mentioned re being able to highlight within a code example

  6. petebacondarwin
    modified the milestones: Backlog, docs-infra-tooling on Jan 10, 2019

  7. angular-robot commented on Jun 4, 2021

    @angular-robot
    angular-robotBot
    on Jun 4, 2021
    Contributor

    Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

    Find more details about Angular's feature request process in our documentation.

  8. angular-robot
    added
    votes required
    on Jun 4, 2021

  9. angular-robot commented on Jun 24, 2021

    @angular-robot
    angular-robotBot
    on Jun 24, 2021
    Contributor

    Thank you for submitting your feature request! Looks like during the polling process it didn't collect a sufficient number of votes to move to the next stage.

    We want to keep Angular rich and ergonomic and at the same time be mindful about its scope and learning journey. If you think your request could live outside Angular's scope, we'd encourage you to collaborate with the community on publishing it as an open source package.

    You can find more details about the feature request process in our documentation.

  10. angular-robot
    added
    insufficient votes
    on Jun 24, 2021

  11. petebacondarwin commented on Oct 9, 2021

    @petebacondarwin
    petebacondarwin
    on Oct 9, 2021
    Contributor

    Closing as this issue has limited benefit for a fair amount of work and has not seen any follow up requests from the current docs team. Also the current docs workflow puts a lot of onus on the engineering team to create and mark up examples, so adding further features to doc-region support without clear need will not help with engineering capacity.

  12. petebacondarwin
    closed this as completedon Oct 9, 2021

  13. angular-automatic-lock-bot commented on Nov 9, 2021

    @angular-automatic-lock-bot
    angular-automatic-lock-botBot
    on Nov 9, 2021

    This issue has been automatically locked due to inactivity.
    Please file a new issue if you are encountering a similar or related problem.

    Read more about our automatic conversation locking policy.

    This action has been performed automatically by a bot.

  14. angular-automatic-lock-bot
    locked and limited conversation to collaborators on Nov 9, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    effort1: hoursfeatureLabel used to distinguish feature request from other issues

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions