Generate basic docs

[djbe]

Hopefully we can automate this. Purpose would be to have a basic (for starters) website with our existing documentation, that would be generated from the latest available release.

First point of discussion: what will we use to generate the docs? Some sites use Jekyll, some use Jazzy. And I'm sure there are many more tools available.

[AliSoftware]

Ping @ilyapuchka @krzysztofzablocki @kylef any feedback for generating docs for your tools?

It feels to me like jazzy is more to generate documentation from the code comments, to have a documentation about the classes of a library for example, not for end-user documentation of our tools (like how to write a config file, etc… basically what we have in https://github.com/SwiftGen/SwiftGen/tree/master/Documentation )

But otoh I seems like you're using jazzy to generate Stencil & Sourcery documentation websites? So does that mean that jazzy is able to generate static content from markdown files as well?

Or should we instead use Jekyll to simply transform our markdown documentation into a static HTML website, since we don't plan to generate documentation for SwiftGen's own code and classes, but nicely presented documentation for end-user we wrote in those markdowns?

Any advice welcome :wink:

[ilyapuchka]

Stencil uses Jekyll I think, Sourcery uses jazzy, it indeed allows to add static files, see our guides folder (you should just mention those files in jazzy config, otherwise they will appear under "other guides" section). With Sourcery jazzy is better, I think, because the main way to use it and thing we need to document is our data models interfaces, the rest can be described in additional guides (which can be either part of this generated doc or can be served separately). For tools like Stencil I feel that there is no big profit from using jazzy, as the source code interface is not what users interact with when they use Stencil (i.e. if we put documentation for for-loop in ForNode documentation comment the generated doc will have this ForNode reference in the doc structure, which tells nothing to user and even harms in my opinion). With SwiftGen I think it's the same situation as with Stencil, users interact with its command line interface and not with its API (unless you want to have a separate docs for devs)

[AliSoftware]

Ok that's what I thought, thanks for the feedback.

I think we'll use Jekyll then. We could add jazzy later if we plan to create developers/contributors documentation, but the first goal of this website is clearly to have end-user-oriented docs, mainly driven by our guides written in markdown and clearly not by our code comments, so as you said Jekyll is better suited in that case.