-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs: Refactor API Documentation Generator #8903
base: dev
Are you sure you want to change the base?
Docs: Refactor API Documentation Generator #8903
Conversation
…ers" This reverts commit 2ec8c97.
…t for some "see cref" links.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## dev #8903 +/- ##
==========================================
+ Coverage 89.82% 90.47% +0.64%
==========================================
Files 412 398 -14
Lines 11878 12375 +497
Branches 2364 2403 +39
==========================================
+ Hits 10670 11196 +526
+ Misses 681 628 -53
- Partials 527 551 +24 ☔ View full report in Codecov by Sentry. |
Just checking: does it support |
Would you able to do this testing #3595 |
Maybe I'd be good idea to leave the code of this in the |
Why did you change Some incorrect descriptions: I only checked a few pages manually. When I was refactoring the code for API documentation, often some change was manifested only in a bug in a few properties on a few pages. This is why I wrote #3595 to be sure I don't break documentation. As you see, unfortunately, manual testing isn't enough :( |
I'm pretty sure |
Thanks for checking some pages! I agree, it's really tough to get every detail just right, like dealing with reflection names. Hopefully I can get some automated tests built from your great test code. |
…m/jperson2000/MudBlazor into feature/docs-generator-tagsupport
…m/jperson2000/MudBlazor into feature/docs-generator-tagsupport
…mponents are tested as before.)
…nerated file instead of "DocStrings"
…m/jperson2000/MudBlazor into feature/docs-generator-tagsupport
…at documentation was actually found, and that a link to the example exists for components. Added ~400 tests.
Alrighty, after almost a month, I think this Docs refactor is nearly ready to review! There are some things I still have to improve like documenting method parameters and enums/fields, but I think the site is in good shape to look at. Here are the major differences to look for:
Let me know if you'd like any UI changes, and I'll bring this out of draft once I have the last pieces done in about 2-3 days. Thanks @ScarletKuro @henon @danielchalmers @mckaragoz @Anu6is for your valuable feedback as always! Steps to Test
|
Thanks for taking into account so much of my feedback, I appreciate that a lot :) On mobile:
Accessibility (cc @igotinfected what do you think? screenshots above):
Other:
|
…ported by @danielchalmers. Improved accessibility and display on mobile devices.
…m/jperson2000/MudBlazor into feature/docs-generator-tagsupport
Great catches as always, @danielchalmers ! I removed the |
…zor#3595. Will fix code to pass tests soon.
@henon I added API docs tests for all of the legacy API URL's based on #3595. Thanks again for the reminder, and I still have your suggestion on my list to add public types to the main MudBlazor search as part of this PR. An example of failed API URL tests: https://github.com/MudBlazor/MudBlazor/actions/runs/9249343454/job/25441037707?pr=8903 |
Great, I'll check out your code and run it for a thorough review soon. |
Below is not a comprehensive review, but only a report of a few issues that I noticed without a longer analysis, which is still needed. Things that are less user-friendly in the new doc:
Bugs:
On https://localhost:5001/api/MudAutocomplete%601 why are there event callbacks "OnKeyDown" and "OnKeyUp" in the "Properties" section and not in the "EventCallbacks" section?? Why did you remove the EventCallbacks section?? Generally, you removed my two improvements: |
I think this needs more argumentation why this order is supposed to be so meaningful. I supect it is based on personal preference. Others may say that Appearance, List appearance, Behavior, List behavior, Data, Validation, ... etc is a better order. In the end, alphabetical is a good order if people can not agree on a "correct" order. |
@henon: Maybe it is a personal preference. I hoped that for many the current order could be beneficial. I could argue why the current order is beneficial, but on the other hand, if it is beneficial then the benefits should be visible at least for some of us. So instead of arguing I just asked here: #9077 what you prefer. If nobody prefers the current order then it is obvious that it was only my preference. |
Sorry, I meant the #9077 discussion above. |
Thanks for the valuable feedback, @iwis ! This is a draft PR with a ground-up rewrite of the docs compiler so that we can access documentation from anywhere in the MudBlazor docs web site via models, and without Reflection. Thus, a lot of work has to be done to restore features like the ones you mentioned. Please don't think I'm "taking features away" from you; on the contrary, I'm taking all feedback like yours into account to make sure this isn't a step backwards when it's finally ready for a formal review in a few weeks. I'll tag you for additional feedback once I get more features implemented. |
Description
This update refactors the API Documentation generator to add several features:
ApiPage.razor
to useThe new documentation generator has these features:
<summary>
and<remarks>
elements<c>
element (converted to<code>
)<para>
element (converted to<p>
)<see cref
linksThis update also adds Documentation Coverage metrics during builds:
This update also makes a few minor code cleanup changes:
Paths
class is now staticHow Has This Been Tested?
The
TestsForApiPages
test generator was updated to use the newApi
Blazor page when generating tests. A big change is that we now test all public types, not just types inheriting fromMudComponentBase
. This resulted in an additional ~400 tests being generated during builds.Also, per #3595, an additional bank of tests are now generated which test the legacy API URL's. This will ensure that users who have bookmarked the old API page will still work properly.
The total API docs tests increased from ~150 to ~600.
Type of Changes
Checklist
dev
).