Docs: Add Support for "<seealso />" Links #10314
Conversation
|
Not sure it's worth renaming |
It's being moved from DocsPageHeader to DocsPage so it will create a diff anyway, and TypeName is more encompassing for non-component pages. I'd be surprised if it generates conflicts as it's in a part that is rarely edited too. |
|
The docs/examples button should be a link instead of a button. Will try to get more feedback later. Love the direction this is going! |
Thanks, @ScarletKuro , the parameter had moved up a level to the |
Oops, I replied before reading Daniel's comments lol. Well, I'm fine moving those to another PR if that feels better. |
Ok, I didn't notice that during scrolling, then nvm above. MudBlazor/src/MudBlazor.Docs/Components/DocsPage.razor.cs Lines 74 to 84 in f7c38eb |
Ok sure, I think I just didn't know how to follow the parameter state like with other controls, but I'll update this to use the same pattern. It makes me want to use that at my day job somehow as well! |
… once they've been moved to another project.
…on2000/MudBlazor into feature/docs-seealso-links
|
Ok, I've rolled back the other changes for now, but there are still a bunch of whitespace changes in this PR. Should I roll those back as well to make this easier to merge @ScarletKuro ? |
Considering the low amount or parameters and that you don't need to set value of the parameters inside the private string _typeName = string.Empty;
private string _type = string.Empty;
[Parameter]
public string TypeName { get; set; }
protected override void OnParametersSet()
{
// Can crete SetTypeName to not duplicate logic
_typeName = TypeName?.Replace("%601", "`1");
_type = value == null ? null : ApiDocumentation.GetType(_typeName);
}
protected override void OnInitialized()
{
// Can crete SetTypeName to not duplicate logic
_typeName = TypeName?.Replace("%601", "`1");
}You just need to make sure that you only read from the |
src/MudBlazor.Docs/Pages/Components/Typography/TypographyPage.razor
Outdated
Show resolved
Hide resolved
You can keep these changes. |
Maybe, you don't even need the |
If a user navigates to the same page but for a different type, the TypeName will change but |
|
This is a really cool feature. Thanks for adding that @jperson2000 |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## dev #10314 +/- ##
=======================================
Coverage 91.43% 91.43%
=======================================
Files 418 418
Lines 13226 13226
Branches 2538 2538
=======================================
Hits 12093 12093
Misses 554 554
Partials 579 579 ☔ View full report in Codecov by Sentry. |
|
Does this PR fixes? |
Yes, the link to a component page will now only appear if the type is mentioned in |
|
Don't forget to update your branch as we got new component Heatmap #10263 |
|
This pull request sets up GitHub code scanning for this repository. Once the scans have completed and the checks have passed, the analysis results for this pull request branch will appear on this overview. Once you merge this pull request, the 'Security' tab will show more code scanning analysis results (for example, for the default branch). Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results. For more information about GitHub code scanning, check out the documentation. |
…ests incorrectly expected example links to exist.
…on2000/MudBlazor into feature/docs-seealso-links
| public List<Type> TypesWithExamples = | ||
| [ | ||
| typeof(MudContainer), typeof(MudGrid), typeof(MudItem), typeof(MudHidden), typeof(MudBreakpointProvider), typeof(MudChip<object>), typeof(MudChipSet<object>), | ||
| typeof(MudBadge), typeof(MudAppBar), typeof(MudDrawer), typeof(MudDrawerHeader), typeof(MudDrawerContainer), typeof(MudDropZone<object>), typeof(MudDropContainer<object>), | ||
| typeof(MudDynamicDropItem<object>), typeof(MudLink), typeof(MudMenu), typeof(MudMenuItem), typeof(MudMessageBox), typeof(MudNavMenu), typeof(MudNavLink), typeof(MudNavGroup), | ||
| typeof(MudTabs), typeof(MudTabPanel), typeof(MudDynamicTabs), typeof(MudProgressCircular), typeof(MudProgressLinear), typeof(MudDialog), typeof(MudDialogContainer), | ||
| typeof(MudDialogProvider), typeof(SnackbarService), typeof(MudSnackbarProvider), typeof(MudSnackbarElement), typeof(MudAvatar), typeof(MudAvatarGroup), | ||
| typeof(MudAlert), typeof(MudCard), typeof(MudCardActions), typeof(MudCardContent), typeof(MudCardHeader), typeof(MudCardMedia), typeof(MudDivider), | ||
| typeof(MudExpansionPanels), typeof(MudExpansionPanel), typeof(MudImage), typeof(MudIcon), typeof(MudList<object>), typeof(MudListItem<object>), typeof(MudListSubheader), | ||
| typeof(MudPaper), typeof(MudRating), typeof(MudRatingItem), typeof(MudSkeleton), typeof(MudTableBase), typeof(MudTable<object>), typeof(MudTablePager), | ||
| typeof(MudTableGroupRow<object>), typeof(MudTableSortLabel<object>), typeof(MudTd), typeof(MudTh), typeof(MudTr), typeof(MudTFootRow), typeof(MudTHeadRow), | ||
| typeof(MudDataGrid<object>), typeof(Column<object>), typeof(FilterHeaderCell<object>), typeof(FooterCell<object>), typeof(HeaderCell<object>), typeof(HierarchyColumn<object>), typeof(MudDataGridPager<object>), | ||
| typeof(TemplateColumn<object>), typeof(MudSimpleTable), typeof(MudTooltip), typeof(MudText), typeof(MudOverlay), typeof(MudHighlighter), typeof(MudElement), | ||
| typeof(MudFocusTrap), typeof(MudTreeView<object>), typeof(MudTreeViewItem<object>), typeof(MudTreeViewItemToggleButton), typeof(MudBreadcrumbs), typeof(MudScrollToTop), | ||
| typeof(MudPopover), typeof(MudSwipeArea), typeof(MudToolBar), typeof(MudCarousel<object>), typeof(MudCarouselItem), typeof(MudTimeline), typeof(MudTimelineItem), | ||
| typeof(MudPagination), typeof(MudStack), typeof(MudSpacer), typeof(MudCollapse), typeof(MudStepper), typeof(MudStep), typeof(MudRadio<object>), typeof(MudRadioGroup<object>), | ||
| typeof(MudCheckBox<object>), typeof(MudSelect<object>), typeof(MudSelectItem<object>), typeof(MudSlider<int>), typeof(MudSwitch<object>), typeof(MudTextField<object>), | ||
| typeof(MudNumericField<object>), typeof(MudForm), typeof(MudAutocomplete<object>), typeof(MudField), typeof(MudFileUpload<object>), typeof(MudToggleGroup<object>), typeof(MudToggleItem<object>), | ||
| typeof(MudDatePicker), typeof(MudDateRangePicker), typeof(MudTimePicker), typeof(MudColorPicker), typeof(MudButton), typeof(MudButtonGroup), typeof(MudIconButton), | ||
| typeof(MudToggleIconButton), typeof(MudFab), typeof(ChartOptions), typeof(Donut), typeof(Line), typeof(Legend), typeof(Pie), typeof(Bar), typeof(HeatMap),typeof(StackedBar), | ||
| typeof(TimeSeries), typeof(MudTimeSeriesChartBase), typeof(MudTimeSeriesChart) | ||
| ]; |
There was a problem hiding this comment.
This section is used by the test generator to figure out which types should have associated example pages. These types come from the types mentioned in MenuService. Since we can't link to MenuService directly, the types have to be duplicated here. Hopefully that's okay.
There was a problem hiding this comment.
@jperson2000 this breaks my reflective Docs Compiler since this now requires a reference to MudBlazor. IDK if theres another way to do this?
There was a problem hiding this comment.
@jperson2000 this breaks my reflective Docs Compiler since this now requires a reference to MudBlazor. IDK if theres another way to do this?
What does the "now" mean? Even before the PR the compiler was referencing the MudBlazor and some types were used, proof:
This is the used referenced before the PR merge.
There was a problem hiding this comment.
Yeh sorry I meant this is a new static type that I noticed when merging this into my work. In my work I was already loading the assembly at runtime
There was a problem hiding this comment.
Is there a place we could move MenuService where it can be accessible by both the Docs and Compiler projects? If so, then I can use it to get the types with examples, and delete this TypesWithExamples property.
|
Okay guys, this is finally ready to review and all tests now pass. The docs tests needed a change to indicate which API docs pages should have a link back to an example page. I wish we could access |
Hi @danielchalmers is this during a build? Any logs |
@mikes-gh It was during debug after I navigated. Best type of logs to send you? |
|
Can you give steps for a repo please. |
|
Apologies, I can't provide in depth info this week, but it was an issue before this PR so should be safe to merge. @mikes-gh |
henon
changed the title
|
Thanks @jperson2000 ! |
|
@jperson2000 This PR seems to remove the API link on components page. Is that intended? |
Description
This update adds support for
<seealso cref="" />and<seealso href="" />links in the API documentation. Links are detected by theMudBlazor.Docs.Compilerand are available to the docs web site via the newDocumentedType.Linksproperty. Additionally, the newApiSeeAlsoLinkscomponent can display all of the see-also links for a given type, which is now available at the bottom of API documentation pages.For example: Writing the following
<seealso />tags for theBarchart component:... will produce the following See Also section on the
BarAPI documentation page:See also links can also use the
hreftag for external links, as well as inner text:Linking From Non-Component Types to Component Examples
In some cases, a type such as
MudDrawerHeadermay not have its own example page, but should still be linked to a different component,MudDrawer. These links are controlled via theMenuService._docsComponents, as shown below:How Has This Been Tested?
Since this change affects the entire docs web site, testing involves regression testing the entire MudBlazor docs site. For component and API pages, the following steps were done:
Type of Changes
Checklist
dev).