Introduce documentation website using Mui
Closed this issue · 18 comments
Since the library now is usable, are you planning on building a docs application like Feliz/Recharts/Plotly/etc. do? This is probably the most important part of the library being practically usable and lowering the entry barrier.
That would be great. I have no experience doing that, so any help/PRs are most welcome!
Please check out the docs application in Feliz and follow that format if possible, it is just another Elmish application. Though I am using Bulma for styling the sidebar, maybe something from Mui (drawer?) would be more appropriate for the layout. The only twist of the application is that it can render markdown files combined with live samples, I am sure the code is pretty self-explanatory but if have any questions please let me know.
Thanks! But how is it hosted? (Edit: I see it's using GH pages. I've never used that before, though.)
Another thing though: Does the documentation have to be an actual demo? IMHO it's much simpler to just show/explain the important stuff using Markdown files directly on GitHub (like the Giraffe documentation does). I like single-file documentation for the reasons described in this blog post.
It is really simple, create a branch called gh-pages from master (easy using github UI) then publish the compiled website contents into that branch. So when you do npm run build (in case of Feliz), you get a static website inside of the public directory where it has index.html at the root. Then I use a npm package called gh-pages to do the publishing for me like this:
// publish.js
var ghPages = require("gh-pages");
var packageUrl = "https://github.com/Zaid-Ajaj/Feliz.git";
console.log("Publishing to ", packageUrl);
ghPages.publish("public", {
repo: packageUrl
}, function (e) {
if (e === undefined) {
console.log("Finished publishing succesfully");
} else {
console.log("Error occured while publishing :(", e);
}
});And every time I want to publish a new version I just go:
npm run build && node publish.js
The first command compiles into a static website and the second just runs publish.js using node and you are done!
Last thing of course you have to tell github that you are using gh-pages for hosting, go to repository settings and then:
Does the documentation have to be an actual demo? IMHO it's much simpler to just show/explain the important stuff using Markdown files directly on GitHub
I understand the points in that blog post but in case of React components, having live and working samples is crucial because users will want to see how the components look like and which use case fits their needs the most, take material UI for example has excellent documentation because you can play around with the components before trying anything out.
Not only the users want to see things live, it is for you as well to test the components and see that they do what they are expected to do per use-case etc.
As for making the documentation easy to follow, you can simply make one giant markdown file following the same structure of DOCUMENTATION.md and have the live samples embedded in there. I might do just that as well in Feliz documentation because it is getting more and more examples (plus for easier navigation)
It is really simple, [...]
Thanks a lot!
I understand the points in that blog post but in case of React components, having live and working samples is crucial because users will want to see how the components look like and which use case fits their needs the most, take material UI for example has excellent documentation because you can play around with the components before trying anything out.
I completely agree! :) But Feliz.MaterialUI is just bindings for MaterialUI. For maintainability reasons, I have absolutely no intention of creating an F# version of the excellent MUI documentation. :) (Anyone else is welcome to contribute, of course. But that seems like a maintenance nightmare, given that the MUI docs are updated all. the. time.) So it'd just be the odd demo. I think it's just as useful to leave the actual demos to the MUI docs, and clearly demonstrate in the Feliz.MaterialUI docs how the MUI concepts map to F# (which for the most part isn't really that hard to get, since Feliz is such a simple DSL 👍).
As for making the documentation easy to follow, you can simply make one giant markdown file following the same structure of
DOCUMENTATION.mdand have the live samples embedded in there.
That would still require all the infrastructure and maintenance burden of the live examples, which is most of the reason I'd rather stick to raw markdown documentation (for now, at least).
I have absolutely no intention of creating an F# version of the excellent MUI documentation
Duplicating the docs from Mui is out of the question but a simplified version is very much doable and will not change unless there are breaking changes. Having a menu item called "Components" that has a number of child menu items like "Button", "TextField", "AppBar" etc. with each of these showing the basic usage of the component in question with at least one example ("this is how a default button looks like using this piece of code"), very simple stuff but it shows that the bindings actually work and more importantly when they don't.
Making a docs app has helped a lot with Feliz (especially with Recharts and PigeonMaps) in making sure that whatever the binding supports actually works and sometimes I had to workaround the original library limitations in the binding.
Even if you don't make a full docs website like Feliz does, at least include a demo project which uses different components that someone can run it locally by cloning the repository (though I would much rather see a docs application like the rest of the Feliz ecosystem libraries do)
it shows that the bindings actually work and more importantly when they don't.
Sounds like this is more of a job for automated tests? Might be complicated, though. I have no experience with UI testing. Demos seem like a good middle-ground, though it'll just be a "smoke test" of sorts since only a few components/props/combinations will be demoed.
I would much rather see a docs application like the rest of the Feliz ecosystem libraries do
I'll see what I can do. I'm rather busy at least until December, so I can't make any promises when I'll be able to get to it. (Hence my inclination toward solutions with as little maintenance as possible; in the end, it allows me to cover more.)
Is it possible to avoid "polluting" the repo root (which is now very clean and simple) with node/yarn/etc. infrastructure stuff, and keep everything doc/demo-related in a subfolder?
Demos seem like a good middle-ground, though it'll just be a "smoke test" of sorts since only a few components/props/combinations will be demoed.
That would be a great start already, even with small number of demos!
I'll see what I can do. I'm rather busy at least until December, so I can't make any promises when I'll be able to get to it. (Hence my inclination toward solutions with as little maintenance as possible; in the end, it allows me to cover more.)
Sure, no rush
Is it possible to avoid "polluting" the repo root (which is now very clean and simple) with node/yarn/etc. infrastructure stuff, and keep everything doc/demo-related in a subfolder?
Of course, just put the package.json inside of of docs or demo directory (however you want to call it) and that directory becomes the root of your client application. Then you can run your npm commands from that directory or have a build script with fake that delegates the commands from the repo root
I have now added a usage guide to the readme, so at least there's something.
Good stuff! Would also be nice to include a section how to get started from scratch:
dotnet new -i Feliz.Template
mkdir MuiTest && cd MuiTest
dotnet new feliz
cd ./src
femto install Feliz.MaterialUI
That would be great. Though it seems to assume Femto is already installed, and there's some overlap with the "Installation" part of the guide. Perhaps a new "Getting started" guide could replace (or be merged with) the current "Installation" guide.
A PR would be welcome! :)
I have started looking at this. No ETA.
A skeleton is now up at https://cmeeren.github.io/Feliz.MaterialUI/
You don't have to link to it yet; I'll let you know when there's something of interest there.
Note that since npm run build outputs to deploy, I had to change ghPages.publish("public" to ghPages.publish("deploy" in publish.js.
By the way, when compiling the app using npm run build, I get the following warnings:
WARNING in asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).
This can impact web performance.
Assets:
vendors.4847c4212474659fdb29.js (390 KiB)
WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.
Entrypoints:
app (452 KiB)
vendors.4847c4212474659fdb29.js
style.css
app.4847c4212474659fdb29.js
WARNING in webpack performance recommendations:
You can limit the size of your bundles by using import() or require.ensure to lazy load some parts of your application.
For more info visit https://webpack.js.org/guides/code-splitting/
Isn't tree shaking activated in the Feliz template (which I have based the docs app on)?
Isn't tree shaking activated in the Feliz template (which I have based the docs app on)?
Tree shaking is enabled, I think this bundle size is pretty normal for Mui (though I would first need to compare it with non-Fable version)
The recommended limit (244 KiB) is for JS projects, Fable adds it's own library functions so there is some overhead from there
Tree shaking is enabled, I think this bundle size is pretty normal for Mui (though I would first need to compare it with non-Fable version)
Interesting. Even though I currently barely use any components?
Done, it's up now at https://cmeeren.github.io/Feliz.MaterialUI.