Just as gh-pages are it's own branch, perhaps you can make the docs its own branch, as opposed to it's own repo. I have very little git-fu, but maybe there can be a doc build step (in this new doc branch) that sticks generated man pages into a desired other branch (with default is master).
Some counter point:That said, from a hacker side, I didn't really care that I had to add a bunch of extra packages to make docs, but those dependencies were readily available on my system. If the docs are in its own directory and the dependencies are only required if I 'make docs', then does it matter to me where they live?
From a package maintainer perspective, they might make some sort libnanomsg-doc package separate from a dev and runtime package. Having it as a separate branch or repo would make this a bit more complex for them, but maybe it's just a matter of having two source packages or them constructing a consolidated source package from two different trees or branches.
-Evan On 08/13/2013 09:02 AM, Martin Sustrik wrote:
On 2013-08-13 11:41, Paul Colomiets wrote:The only reason to put documentation in the same git repository, is to update docs simultaneously with the code, and to accept patches for code and docs in one go. But this is fairly good reason to do so.Frankly speaking, the more I am thinking about the whole documentation stuff, the more confused I am. There's too much intersecting domains there: global-scope (online docs), release-scope (the source package), repo-scope (what you get when you do git clone) and local-scope (generated by make). Then there are things that maintainers should do, things that other developers should do, things that users of source package should do and things that users of distro packages should do. Then there are many instances of the docs to keep in sync: distros, source packages, website, git repos, the library itself etc.All in all, it's a mess.However, separating the library from the docs at least clearly separates the mess from the rest of the system. You simply commit the generated man pages into the library repo. That's a pretty simple and easy-to-follow process. It also solves the problem of delivering the man pages to everyone, including people building from git and without the appropriate tools installed.Generating the docs may still be messy, but at least it's in a separate repo and thus it confuses much smaller community :)Anyway, I don't feel very confident about the whole stuff, so feel free to disagree.Martin Btw, here's the visulisation of content distribution channels:nanomsg-doc ---+----> nanomsg github repo ---> source packages ---> distro packages| | | || +-> /usr/share/man +-> /usr/share/man +-> /usr/share/man| +----> gh-pages github repo ---> website | +----> IETF RFC editor | +----> ...
