make documentation part of the code repository

[xlotlu]

In my opinion, docs should be part of the product repository, and included / built along with the rest of the website.

The way it is now, there isn't a correlation between code changes and documentation changes (i.e. them being part of the same commit / same PR), and there isn't an incentive to update the docs along with the code. On the contrary actually, the current setup is a deterrent, treating the documentation like some "secondary" item. I think this is likely to result in incomplete examples (as one would normally want to correlate test updates with documentation updates), or simply out of sync docs.

This would also make it possible to build separate docs for each release, which is currently impossible.

Addendum: having to check out 40MB of unrelated stuff (showcase, blog posts etc.) to update some docs is absurd.

[goanpeca]

@xlotlu indeed this would be nice, but development docs are different from user oriented docs so I think development docs (make life easy for devs and contributors) make sense as part of the repo whereas User oriented docs (like what we have) still make sense to me as a separate thing.

[xlotlu]

@goapeca but... but... that would make maintenance even messier. Besides, user docs are linked to features in the code, they're not much different from developer docs. One new feature should reflect in user docs as well as API docs. One deprecated feature, the same. I don't think I've ever seen another project with docs separated from the code, much less so with half in one place and half in the other.

[dwt]

I would like to second @xlotlu here. The docs really should be part of the code, as they are relevant for the version of the code you are using, and right now it is not even possible to find out what version of the code is documented.

So for example: A new feature worked on in a branch, cannot at the same time be documented.

[runfalk]

I think @xlotlu's suggestion is pretty much what we agreed to do. PR lektor/lektor#787 should really get merged into this repository but is being held up because we need to properly host the docs somewhere and point the domain name to it. There is also an open PR (#302) to replace Travis with GitHub actions which would probably be the first step.

[dwt]

@runfalk This probably comes off a bit trollish, but have you guys considered hosting the docs on a GitHub page? The default-domain from the lektor repo would be great as a first step (afaik) and a custom CNAME can always be set in a second step.

[runfalk]

Fair question, and yes #302 actually uses GitHub pages. I think it's more a matter that no one has considered the intermediate step and most maintainers don't have DNS access so the PR has just stalled.

EDIT: This is the link to it FWIW https://lektor.github.io/_deployed-lektor-website/

[xlotlu]

Indeed, the consensus was to port the docs, and whatever else makes sense, e.g. the installation script. There's also an issue tracking this over on the other side, lektor/lektor#756.

The lektor/lektor#787 PR has also stalled because, although importing of the docs is covered, one needs to separate the website logic away from this repo. I have wrote some starter code to cover this, but there's plenty more work to make sure css works and only contains docs-related stuff (and conversely, this repo only covers website stuff). Since I am not involved with lektor anymore I'm unlikely to follow up on it, but I can answer any questions and provide guidance. The script is there for anyone to pick up.