[nanomsg] Re: Separating the library from the docs
- From: Paul Colomiets <paul@xxxxxxxxxxxxxx>
- To: nanomsg@xxxxxxxxxxxxx
- Date: Tue, 13 Aug 2013 17:21:26 +0300
Hi Martin,
On Tue, Aug 13, 2013 at 4:55 PM, Martin Sustrik <sustrik@xxxxxxxxxx> wrote:
> Hi Evan,
>
>
>> 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?
>
>
> No, it doesn't really matter it it's a different directory, different branch
> or different git repo. The only point is to keep the two fully separate and
> copy generated docs from the doc-component to the lib-component.
>
Well it matters. Having *different branch*, means tags for docs will
have different name from tags for source (e.g. v1.0.0 vs v1.0.0-docs).
It's also means two pull requests, so two different issues/tickets on
github for each feature for docs branch and for master. It's very
inconvenient.
Having *different git repo*, still means two patches, two pull
requests and two issues opened, but at least it's more clear where
pull request should go. And probably all feature pull requests will go
without docs :)
*Different directory* is ok, from a perspective of patches. But may be
inconvenient when updating docs after release. Also if you keep
generated docs alongside with non-generated docs in single git, does
updating generated docs should be in the same commit or not? Do you
have to accept patches with generated files together?
> The only reasons for separating the repos the would be not to confuse users
> (like believeing they have access to doc sources when they are actually
> working with library source code) and not to confuse the toolchain (two
> ./configures in a single project?).
>
That's a smallest reason to me. It's easy to implement "make doc" in
any case, as easy as implementing "./configure --without-docs"
All in all, I'd say the most up to date man pages should be tightly
coupled with the code. And other docs should be in other repository.
And a release tarball should probably contain pre-generated man pages,
but better keep them off the git repository.
--
Paul
Other related posts:
