[Docs] Using a tool to generate a documentation site

[csshugs]

Since we released v6.0.0 (yay!), the only real thing that's missing currently is a proper documentation site. We do have a separate repo for this, however several people now mentioned to me that it would make more sense to generate the documentation straight from the source code. I do agree, keeping the code itself and its respective documentation in the same exact file and not separated in two repositories is far better for the sake of maintainability. So being able to generate a real documentation site automatically from the code sounds like a reasonable approach for us to go.

We already discussed the possibility of using SassDoc, which we couldn't agree on and I personally still can't because of the mentioned reasons.

Another tool I do not have any experience with at all would be KSS. Without knowing the tool, it looks a bit more complicated to incorporate it into the project. But I will definitely have a look at it.

A tool I do have worked with is mdcss. Just like KSS, it let's you write CSS comments in a special syntax and allows you to use markdown in this comments from which a documentation will be created.

Conclusion

As I already mentioned, I consider it a sensible idea to generate our documentation right from our source code. For this we have to use a proper tool. I think both tools—mdcss and KSS—could handle this. I'll investigate a bit deeper in both of them to find out the pros and cons of each of them. But maybe there are other tools out there that I missed?

[herzinger]

Okay, this makes me really happy.

While I still don't agree with the reasons for leaving SassDoc out - since it can do all the others can and is much better at documenting the tools layer, since it's done specifically to document sass, not css, and treats it as a real programming language, not just styling - this seems like a decent compromisse. Mdcss seems like the simplest and more appropriate of the two (assuming the discussion os SassDoc is really dead for good).

[dennisfrank]

I do like the idea of a automatically generated documentation from CSS/Sass comments. I agree with @herzinger that it would be important to not only document CSS but Sass functionality as well.

inuitcss also requires at least as much documentation for a describing the general idea (and ITCSS) and examples. I am not sure if existing CSS doc tools allow such flexibility.

https://css-tricks.com/options-programmatically-documenting-css/

[daiky00]

so when is the documentation going to be ready?

[yourownmood]

We could automate, the building/generating of the docs in CircleCi and publish this on a docs branch which could be linked to the github page(s) of this repo.

[LayZeeDK]

Fractal is worth a mention.

[csshugs]

inuitcss also requires at least as much documentation for a describing the general idea (and ITCSS) and examples. I am not sure if existing CSS doc tools allow such flexibility.

I agree and after thinking about it for a while, I am convinced that building a custom website separate from this repository is the most pragmatic way to go. As much as I’d love to generate a website automatically from all the source files, I don’t see any tool handing this in the way we need it, which is documenting the individual modules (i.e. mostly the objects) as well as the Sass functionality. Combining tools like SassDoc and Kss with custom pages for ITCSS docs etc. seems like a mess.

We are going to transfer this topic to the inuitcss website repo. But I can already say, that IMO this is something we should do for v7 of the framework, because I think that’s the way we are heading right now.