unoplatform
Docs(Storage): Improve and add Storage Documentation
GitHub Issue (If applicable): closes #2630
PR Type
What kind of change does this PR introduce?
- Documentation content (samples) added
What is the current behavior?
Missing almost whole Uno.Extensions.Storage Documentation currently
What is the new behavior?
Added Storage usage samples
PR Checklist
Please check if your PR fulfills the following requirements:
- [x] Docs have been added/updated which fit documentation template
- [x] Contains NO breaking changes
- [x] Associated with an issue (GitHub or internal) #2630 => AND this documentation is frequently asked for!
Other Information
#2824 needs to be merged first, as its containing the relevant files like the referenced Getting Started with Storage and includes Prerequisites md file
@DevTKSS very nice!
With the steps here for the docfx instructions, I think you are running into issues because your changes are on a fork. I'm actually not sure if there is a way to work around that. @agneszitte Are you aware of anyway that @DevTKSS could test out their docs changes in a local build of docfx?
@kazo0 with the linked instructions that only is successfull at first local build, but failing afterwards for:
- docfx finding too many issues on the imported extenals, which I could not even name the source, even if I let it do a stacktrace of 1000 that seem to be far more than this :( so currently, I only be able to let the CI pipeline in the PR check it, which is as you will know, not at all what should be the target reading local build docs. I did already create my own project with docfx generated docs locally, which did well, but as soon as it comes to uno docs which importing externals thats failing constantly
But additionally to be said, here on this PR to the mentioned PR 2734, only the links on the overview are added and I think the samples+structure+Reference of the other one might be better. what do you two say to this?
@kazo0 can you or @agneszitte tell me if this version here or the docs (excluding the added code) on the other pr are preferred and if I should maybe instead put them in this PR to apply SOC?
@DevTKSS Yes I would say we can centralize all docs specific changes from both PRs into this one, that would be best
@kazo0 after hours of frustration and with terminal is too short so show the first members of that stacktrace, I set the limit to 90000 lines, not even --log did provide any output. So finally got the start of culprit and it has been something in relation with the styles of the uno template. I do not know .js lang so that has been no option to be solvable there.
But as I mentioned before, on a non uno project - documentation that docfx build and serve did work, so I ended up copy pasting the uno extensions storage build required folders and the -PackagesOnly.slnf into a new folder outside of the extensions repository and to check if that culprit is really the uno template in the end, I replaced the "templates/uno" with the "modern" template name I used for my own projects and 😄
that looks like a reference documentation to me :) next I will transfer the modifyed md files and copy them into my temp-repo folder, so I can this way validate them to look as they should without uno.ui import, without dotnet-serve but with docfx itself.
so seems like docfx dont likes the uno toc regular xref usage, so I had to do some workaround that meant delete the must'nt validate members from the toc(s)
But now it seems like the setup shows the
- Learn Storage Content
- Reference of Storage (without custom Overview Page of Storage Reference)
https://github.com/user-attachments/assets/d13e749f-4b30-43f6-9632-29b0f6aedbc0
on my TODO:
- [ ] check the added Storage Samples and see if that needs some adjustments
downside: since Uno Template overwrites the NavigationBar, there is no navigation possible for a local build with that instead of the modern template, I used also in my own project, for me so xref in toc only manually checkable without serving. Just an Idea, but if it maybe would get considered to actually have a real API Reference, maybe there would be a way to nest the docfx top navigationbar below the main one from the uno homepage? By that I could imagine that would enable to have a clear seperation of the reference to the learning and overview material.
Still in progress, the high count of changed files is resulting from updated image assets for the getting started guide to prepare the How To Starting point and the added reference files.
Really changed files beside of that are most likely far less... About 10 maybe and even most of them are only little formatting changes😅
How To intro started at last commit
So somehow it seems like the high amount of counted files are coming from the commits that has been merged from uno-origin to push back up to GitHub 🤔
[!NOTE] On the files I edited I left some comments that should be checked at review at some point in the end
@kazo0 updated this and split up to #2710 for brevity, please merge this here after the getting started. Would then rebase on top, so this here gets the required files it builds on top of
@DevTKSS Looks like the Conventional Commit check is failing for some of these commit messages:
@kazo0 its on my ToDo list 👍 this evening I am on an event, so planning this for tomorrow. The log of the CI showed that its caused some how through the squashing. Seems like the before messages did somehow cause that.
Do you know if non-members are able to run ci or actions locally? I would only know of running tests but I don't know if there is a way that'll do this for actions... I do have DevOps but I don't think that would change anything to enable test running this before like a local docfx build isn't it?
🤔 The script pr for the import external docs is still pending to be reviewed 😅 thats ready from my side...
@kazo0 it were the doc instead of docs as the Merge Commits are auto generated through github. this one were the only left as option 😆
Should be mergable 🤔 dont know whats currently up with the azure functions, but the commistar is passing
@kazo0 would you be able to help me finish up the 3 storage PR's so they could get merged soon? Got already again requested on the discord server and I just see the action bot label PR after PR of mine without I could really change something on it...
@DevTKSS There are too many PRs that depend on each other to know which one to review first. I'd suggest we avoid doing this as it makes it very confusing to follow and we may be putting the docs into a broken state if the PRs aren't merged all together at the same time.
It's also a problem if we make changes to one PR and we don't remember to adjust the dependent PRs that may be relying on something we changed.
@kazo0 🤔 Like one (1) PR ?
- https://github.com/unoplatform/uno.extensions/pull/2824
What do you mean by "too many" and that one is even linked in the OP 🫤 👀
That PR linked (except from to be synced, which is quickly done) has only stuck on the Hosting Part.