Suggestion: Change how site docs are generated

[kooliokey]

Is your feature request related to a problem? Please describe.

I've noticed there are many instances of documentation missing for public parameters in code and a difference in the documentation on parameters that are documented in code and the site.

Describe the solution you'd like

I'm wondering if we should make the site's documentation generated from reading the documentation comments on the code itself so they always match? I've never done it before, but I know tools generate whole sites with the comments so it should be possible to read them and use them how we want.

Additional context

N/A

Automation Progress

Documentation Page Migrated & Checked - English

• Overview
• Button
• Icon
• Typography
• Divider
• Grid
• Layout
• Space
• Affix
• Breadcrumb
• Dropdown
• Menu
• PageHeader
• Pagination
• Steps
• AutoComplete - Base class properties not showing docs
• Cascader - Base class properties not showing docs
• Checkbox - not all properties are documenting. Generic is causing problems.
• DatePicker
• Form
• Input - Docs from generic base class not showing
• InputNumber
• Mentions
• Radio
• Rate
• Select
• Slider
• Switch
• TimePicker
• Transfer
• TreeSelect
• Upload
• Avatar
• Badge
• Calendar
• Card
• Carousel
• Collapse
• Comment
• Descriptions
• Empty
• Image
• List
• Popover
• Segmented
• Statistic - not all properties getting documentation. Prob affected by something in the "issues found" below
• Table - missing a lot of property summaries
• Tabs
• Tag
• Timeline
• Tooltip
• Tree
• Alert
• Drawer
• Message - done except methods docs
• Modal
• Notification
• Popconfirm
• Progress
• Result
• Skeleton
• Spin
• Anchor
• BackTop

Small Things Found On The Way

• Fix display of OneOf - missing types...just displays OneOf
• Adjust style of methods docs
• Getting XML documentation of methods is not being easy - the format of generics is different than just doing .FullName
• <inheritdoc /> not inheriting

Documentation Translated

This will take more investigation work to implement and we may want to split it into a separate effort. We could implement multiple languages for now by linking a file with the translation in the XML with a custom element.

• Decide on way to do it
• Decide how to allow overriding translation if automated is bad
• Implement automated translation w/ way to override

Possible Improvements

Some things that may be nice to implement in the future

• Remove inherited parameters from documentation and instead show a message like "Inherits API of SuchAndSuch". It would save space.
• Link <see cref="AntDesign.RenderMode"/> to github for file or a page on the site for the file

[ElderJames]

Yes, it would be better if we could implement this way, and it would be better if it could be translated into English and Chinese.

[kooliokey]

I can look into how it can be done. I'm not too familiar with how the docs are currently built though so it might take a while :D

[ElderJames]

Currently just using AntDesign.Docs.Build.CLI to render the markdown files and copy the razor code into json.

[kooliokey]

If anyone wants to see my idea so far on this, I have a branch going in my fork. I ran into a snag on generating the "Overview" page in the components section though because currently it is generated the same a code components but there is no code to use for the documentation.

I also still have to combine the components that are on one page because they function together like anchor and anchor link. I was going to look for an XML documentation element that made sense to basically tell it to combine them so it can stay in the code.

https://github.com/kooliokey/ant-design-blazor/tree/feature/documentation-automation

[ElderJames]

Hi @kooliokey , I've taken a look at your branch, and I think it's great.

But I don't think the component introduction is very elegant, and too much of it will lead to html. This part of the advice is again taken from the markdown file, and only properties and methods are generated through comments. In addition, you need to consider how Chinese is generated. Use the open translation api or something else?

BTW, this would fix #1495 too.

[ElderJames]

Also would fix #2421

[kooliokey]

@ElderJames Glad you like where it is going! I was trying to get all the documentation in code so you get the benefit of it showing in VS Intellisense as well as the site. I haven't dug into ways to format it much yet, but if it sticks to paragraphs and lists that can all be done with XML elements in the summary. We could move back to using Markdown for the descriptions if wanted, but we loose the benefit of it all being in one spot.

For Chinese language...I was thinking of using some sort of API in the build to translate it. I haven't looked much into that piece yet though.

[ElderJames]

We maybe can use this way

https://learn.microsoft.com/en-us/nuget/create-packages/creating-localized-packages

[ElderJames]

Hey @kooliokey , how is it going on?

[kooliokey]

@ElderJames I haven't had much time recently to work on it and I have to send my laptop in for repair so I won't be able to do more until I get that back. I haven't dug much into the translation part yet. Still working on getting the documentation to match the existing as close as I can. I have it combining components onto a single page (like Form and FormItem) but have to make it do it for all of them. There are also some pages that don't have a matching component class that I need to look at (Like the Typography page)

[ElderJames]

Ok, that's fine. Let's see how we could continue this work.

[kooliokey]

I was thinking of adding a custom XML element for use in the documentation comments for linking a markdown file for the site since you mentioned wanting to keep that way available? The Microsoft documentation says it is acceptable to make your own. I figured something like <documentation file="/path/to/file.md" />

[kooliokey]

Update: I've received my repaired laptop back so I am able to continue looking at this again. I plan to start more tonight.

[ElderJames]

good news 👍 welcome back!

[kooliokey]

Update: All English documentation is complete and generating. Will be looking at the translation soon.