[Docs][CI] Ensure docfx links stay valid, prepare future xml API docs options, keep docs simple maintainable and introduce CI integration for this

[DevTKSS]

This Docs/CI Enhancement targets to keep pre / development Branch Docs + Releases API:

• cleanly seperated on their branch (intellisense/markdown suggestion support)
• allow valid API docs and source code linking in docs

Important

docfx docs generation will fail completly or produce invalid Links if we include the metadata step on a branch that doesn't include the to be linked file or src code!

To Ensure the latest docs PR (find linked in Additional Information Section) will not fall on our toes in the future or cause unnessesary additional (automate-able) work for us, we should consider:

• GH Action for PR's md docs changes: If there are only md docs changes (our current build not includes API docs) This should get triggered and add a PR for maybe cherry picking those commits from development onto master? but this will potentially be causing invalid links as soon as we step on to use API docs!

• Enhance/Ensure proper Commit Labels: We should then explicitly keep our commits cleanly seperated and scoped/categorized properly, which would include such relevant changes. It's possible for the commitlint.yml from what I readed by now, to add more allowed labels or similar but we should have this discussed and decided properly, what we want and maybe find ways to do this, which I maybe did possibly not consider here.

• GH Action: Ensure DocFx correct build for API metadata: Pay Attention as soon as we might want to use generate xml docs from any source code via metadata!
  Produce and add API Docs after changes on non-master-merge PR branches:

  • create the API them in this case after their source branch got a relevant PR merge
  • have all docfx docs produced and merged to master (?) or @andrerav what do you think of reusing the gh-pages branch for our docs product then 🤔 ? possibly this is the cleanest way...

• Review & Add DocFx Content Setup for API version support:

  I havn't been successfull by now with the output / dest settings in docfx.json which are linted as depreciated but I see many others still use them and I think this is required to have a proper xml API output control for this 🤔

  • Possibly I will need to ask the docfx team for help, to come to a working setup, but my targeted idea would be something like this in our github.io web docs then:

    

Additional Information

• Merge Development to Master - For work on documentation #845
  @DocSvartz @stagep @andrerav

[DocSvartz]

have all docfx docs produced and merged to master (?) or @andrerav what do you think of reusing the gh-pages branch for our docs product then 🤔 ? possibly this is the cleanest way...

I think it's easier to keep the documentation on a separate branch.
Especially if it is possible to transfer data about api metadata to it.

Until the API documentation is created, it will allow us to work in parallel.
Improving conceptual documentation, regardless of code and release cycle.

The only problem here is the timely description of new features.
But I don't quite understand how placing it on one branch can solve it. (Unless, of course, we set a restriction that a PR with a new feature must also contain a commit with documentation on it. )

[DocSvartz]

GH Action for PR's md docs changes: If there are only md docs changes (our current build not includes API docs) This should get triggered and add a PR for maybe cherry picking those commits from development onto master? but this will potentially be causing invalid links as soon as we step on to use API docs

@DevTKSS Something similar to this is meant ?

---
config:
 
  gitGraph:
    mainBranchName: 'Dev'
---
gitGraph
    commit
    branch PR
    branch Documentation
    commit
    commit 
    checkout PR
    commit id: "feature"
    commit id: "Docs"
    checkout Dev
    merge PR id:"MERGE"
    checkout Documentation
    cherry-pick id: "Docs"
    

Loading

[DevTKSS]

@DevTKSS

I think it's easier to keep the documentation on a separate branch.

Just to clarify:

I do not recommend to have the edited Docs (*.md, toc.yml) on only that one branch, then instead about the produced docs (html, css, js...)

Especially if it is possible to transfer data about api metadata to it.

I assume this to be possible by configuring the gh action we use to produce the docs.
I did not use this until now, but since there is that branch and folder selection and the gh action is doing the work for putting it in the branch and location it's expected to be somehow.

So to have the docfx docs actually served on GitHub.io website without Jekyll, you were needed to edit the Repo's Settings/Pages/ config. Did you do this?🤔

Until the API documentation is created, it will allow us to work in parallel.

Depends on your expectation of ability to check for correctness, if you would assume to have the md files only there, this has the downside, to not be able to validate the docs locally before merging, which should be a validation target To-do.

Are you meaning to have the docfx.json there and merge the branch always in that docs branch, so the md files are there and then deploy, I think someone experienced with Azure Static Websites should take a look at setting a test website function up, so the one or Team reviewing the Docs produced by his PR 😉 can then anyhow validate this even worked.
But if you want my opinion on that, I would don't do this. Potentially breaking most of the time on the toc file and we will get annoyed by never working or "dont touch it, it works but nobody knows why this works." code 😬

Improving conceptual documentation, regardless of code and release cycle.

Of course that makes sense, but what docs would this be?
Things which are already on stable branch?
I think possibly this is also a pro-argument pro backport + version branches which I mentioned on the other Enhancement issue for CI 🤔
I remember that Uno does use a "import external docs .ps1 script but still this only sources a specific commits/branches from their different repos (extensions, toolkit etc) to the core repo, which is the one the docs are deployed at, but they are using Azure and not gh pages for this in the end and not having any api docs by this date which is quite annoying if you may use or want to use copilot or MCP 😅 and it doesn't know of the actual api/can not lookup either.

The only problem here is the timely description of new features.

Yes, I agree this is the difficultest part, which still needs to be investigated 👍

But I don't quite understand how placing it on one branch can solve it.

Which is why you moved it to master branch? 😉 This is mostly about ensuring that your plan wirks. You have been quicker in merging it (<1 Day?) then me in responding to your question there 😅

(Unless, of course, we set a restriction that a PR with a new feature must also contain a commit with documentation on it. )

Not sure if this is possible. The gh action yml docs should tell about the options

[DocSvartz]

So to have the docfx docs actually served on GitHub.io website without Jekyll, you were needed to edit the Repo's Settings/Pages/ config. Did you do this?🤔

Is this what you mean?

• Merge Development to Master - For work on documentation #845 (comment)

[DocSvartz]

Are you meaning to have the docfx.json there and merge the branch always in that docs branch, so the md files are there and then deploy, I think someone experienced with Azure Static Websites should take a look at setting a test website function up, so the one or Team reviewing the Docs produced by his PR 😉 can then anyhow validate this even worked.

I meant the "master branch for documentation" approach.
It only contains documentation and nothing else. (like gh-pages)
It has something like folders:

• articles - md files
• api v1 - where the metadata collected on the master branch is moved (.yml)
• api v2 - where the metadata from the develop branch is moved (.yml)

Possibly I will need to ask the docfx team for help, to come to a working setup, but my targeted idea would be something like this in our github.io web docs then:

This is just a standard conceptual documentation, which they most likely just wrote by hand.

[DevTKSS]

@DocSvartz sorry if it was a stupid question, it's most likely coming from my confusement in general about the real meaning of the word conceptual in this context, because I am implying this to be a synonym for draft from the translation I automatically came up with from englisch -> german.
But now that I actually checked, what this really means instead of just assuming, this makes much more sense😁

Conceptual documentation

In technical writing and software development circles, this term is specifically used to distinguish it from purely procedural content (step-by-step instructions).

thanks for the patience 👍

So "conceptual" is in my previous definition the .md with TOC.
I would maybe suggest a bit different idea of what you have in mind, but I think this would be possible to make work for docs deployment on one branch with a bit modified script like the import-external-docs.ps1 I used to do a PR for in the past and what I have been speaking of here. 🤔

• feat(import_external_docs): add support for contributor Git URLs unoplatform/uno#20667