Docs(docfx): update docfx build locally guide and enhance check-toc capabilitys

[DevTKSS]

GitHub Issue (If applicable): closes #

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting)
• Documentation content changes
• Build or CI related changes (maybe?)

What is the current behavior?

Current docfx guide is outdated and telling to use docfx.console which has been depreciated
see more Information to this here: dotnet/docfx#9100
Link to the Documentation page
The Uno.Extensions Repository is already having the new commands in its Readme.md

Secondary, the check_toc.ps1 does list almoast every href as not linked to a file, because it does not recognize the xref link declaration

Third page is way smaller changes:

• The Getting-started did not at all mention the need to install dotnet before Uno.Check (that is only told on the actual Uno.Check Page) so thats more a reason of completeness of the Quick Start.
• I did frequently notice Beginners ask about Trouble-Shooting Uno.Check and since we did already seperate its Pages (much better from my point of view!) there has been those links been missing.

What is the new behavior?

1. Updated the docfx commands

   • I did left there some commented text, which needs to be checked if the new one is enough.
     Problem with that is, I do not understand the UWPSyncGenerator so deeply to decide this. Currently, those comments do stretch the md line distance a bit (vs 2022 preview) althought its hidden.

2. Added a detailed guide to the usage of check_toc.ps1 along with adding the capability of recognizing and comparing the xref -> uids

• By this it also did uncover the features/windows-xaml-ui-xbind link beeing broken, I did already wonder last days. Was unable to navigate to this page in the docs.
• Second link it did uncover is the only url link in toc and to me it looks okay, but maybe someone would like to check this...
• Another Link I do not know if the url is correct is the now nested Uno.Check Pages I tryed to link from the Getting-Started.
  The old one does have a different signature...
• Because of that new capability of the script, I added a -Verbose Flag for it, so in case of problems, there would be informations available, till which point it came.
• Help needed with the Link to the gif I added to this for showing a workaround for those who might not know these steps until this point, to find not inluded files in vs 2022. I used the docfx documentation way for Image, but its showing only a broken image symbol...
• I dont know if the script change does actually make this to a CI - Build relevant PR but there is told: At the moment it's not part of the CI, so I dont know it should be tested for this again...

PR Checklist

Please check if your PR fulfills the following requirements:

• Docs have been added/updated which fit documentation template (for bug fixes / features)
• Unit Tests and/or UI Tests for the changes have been added (for bug fixes / features) (if applicable)
• Validated PR Screenshots Compare Test Run results. -> building docfx is failing because of missing things it seems to me
  docfx build output.txt
• Contains NO breaking changes -> would not identify it as such...
• Associated with an issue (GitHub or internal) and uses the automatic close keywords. -> I did not see one just my problem with it.
• Commits must be following the Conventional Commits specification.

Other information

Above mentioned

Internal Issue (If applicable):

[unodevops]

⚠️⚠️ The build 158236 has failed on Uno.UI - docs.

[DevTKSS]

The markdown linting pipeline in this case would be greatly more helpful if it would also lint and suggest the solution for image video and links like relative paths and so on before the intending and spaces checks👍🤔

[unodevops]

⚠️⚠️ The build 158359 has failed on Uno.UI - docs.

[DevTKSS]

Currently on Fixing a regex bug, then I will send the updated commits.
Had to delete the commented parts mentioned to satisfy the markdown lints, hopefully anyone could check then if there needs to be something added in relation to the UwpSyncGenerator.

[DevTKSS]

Does a include of Pester tests required check the ui tests checkbook above?
Adding those for the functions of check_toc.ps1 which I now seperated (incl. Documentation of course) to check still listed toc items that I was quite sure that they are linked🤣
But since docfx is still failing to serve because of doc issues in the external nested stuff I am not able to review docs locally😒

[agneszitte]

@DevTKSS Thank you so much for the Pull Request ❤️
I will take the time to review the changes this week and follow up with you as needed

[DevTKSS]

Status update:
Two of three seperated functions of the script to recognize xref and uid plus to compare them did pass successfully the tests

Things might to consider for add able tests and function for uid-xref links:

• casing
• minus between uid allowed but no spaces
• ...

Currently checking on the dot sourcing third script now which should be last before again check on the main script which uses them.

The dot sourcing one might be the most difficult one to setup test for because it has no actual function definition right now, just what it should execute. If it works but test setup has still trouble with its validation I would consider updating the related docs on it and commit to the remote branch so its review-able and maybe get a overseen solution for this.

Since I did add those md files, I did sort them into directory and recognized that not really matching and seperated directorys. Seems like there is the main contributing one and the uno-development one which mainly contains all of the files nested in toc contributing😅
@agneszitte is it considerable to move the documentation related ones at least with git mv so source control has no issues but this setup follows the toc definition?

And I am thinking of, if the scripts might be better places to the testscrips folder instead(paths naturally fitted) to not cloud the documentation itself?

[DevTKSS]

@agneszitte @MartinZikmund commited to remote, unable to fix the Import-TocCheckerUtils.Test.ps1 to pass the check of Get-MarkdownHeader function, while it passed the dot-sourcing before. checking this here:

PS C:\Users\TKSSonja\Projects\uno\doc\articles\check-toc-utilities> . .\Get-MarkdownHeader.ps1
PS C:\Users\TKSSonja\Projects\uno\doc\articles\check-toc-utilities> Get-Command -Name "Get-MarkdownHeader" -CommandType Function

CommandType Name Version Source

Function Get-MarkdownHeader

PS C:\Users\TKSSonja\Projects\uno\doc\articles\check-toc-utilities>

It should have been able to get it from my point of view.
Could someone have a look on this and find the culprit?

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

[DevTKSS]

Some planned to-do at the moment:

• 1. Enhance ./uno/doc/articles/index.md npm guide by adding tabbed content to choose from and include vs code extension options for this (seperate PR to be created, do we need a issue/kind-enhancement before?)
  • 1.1. cspell
  • 1.2. markdownlint
  • 1.3. adding links to ./uno/build dictionary/ preset files
• 2. After check-toc successfully passing:
  • 2.1. Check the now listed toc links
  • 2.2. Get Answer to the preferred link
    • xref ?
    • href with path?
  • 2.3. Add this to docs
  • 2.4. Match at least the now added pages to this
  • 2.5. Add added doc files to the toc and link them in related topics if needed
• 3. Check the docfx issues with external docs in extension and workshops and samples

maybe toc checker can be adjusted to exclude the Readme files which are not cared about in samples, but preferred should be, to add explanation and how to each so it would greatly enhance others to learn from there.

The xref could be better especially because the external area do have quite long paths otherwise.

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

[DevTKSS]

work still in progress

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

[DevTKSS]

@agneszitte three back- questions added to your comments, you might have an answer to? I am on doing throught file to file to validate and xref the links first in the contribution area so would be great if I could implement those changes then in one go:

First comment of yours that's having relevant question to this, would be the links to the dot prefixes templates you said to possibly update to xref.

I am not sure if linking that directly with xref would result in a valid link, does that work?

Second one is the abbreviation things which are somehow strangely do not show correctly as their docs are telling🤔

If that markdig extension does generally not work on uno docs, that should Maybe better get deleted from the docfx.json also beside not using it in the docs itself?

Third one, the possible scripts namespace

I would maybe better want to change to Tests together with the existing test docs also for brevity. The ps setup guide for ps script creation I could just add in the utils or add to the includes folder, because I could not really imagine a currently completely fitting one for this content. The option to "just" link to another website I do not prefer, because at the time I did research fir that information, there has been multiple videos telling they would show how to use ps7 in vs code, but none showed that really, so I would like to just fill that gaps up in that step-list there😅

[DevTKSS]

Where did now that uwp-conversions.md file suddenly come from, that's causing merge conflict...

[unodevops]

🤖 Your WebAssembly Sample App stage site is ready! Visit it here: https://unowasmprstaging.z20.web.core.windows.net/pr-19722/index.html

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

[unodevops]

⚠️⚠️ The build 159995 has failed on Uno.UI - CI.