couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Davis <paul.joseph.da...@gmail.com>
Subject Re: Docs, second try
Date Thu, 21 Jun 2012 14:18:34 GMT
On Thu, Jun 21, 2012 at 8:53 AM, Jan Lehnardt <jan@apache.org> wrote:
> Thanks for the feedback, Paul.
>
> On Jun 21, 2012, at 15:16 , Paul Davis wrote:
>
>> I did some poking through of that docs branch the other day. I'll try
>> and summarize my thoughts but I preface this with the fact I've been
>> up all night debugging.
>>
>> The biggest technical issues I see is that I really dislike having the
>> non-autotools build inside the autotools build. From the discussion
>> I've seen so far this seems to make things fail a lot in icky ways.
>> The raw make system that the docs uses seems straightforward enough
>> that redoing it to be a proper autotools build just seems like a
>> matter of time for someone that knows autotools. But I'd prefer this
>> were fixed before inclusion or it'll end up being one of those "we'll
>> fix it later but never do" scenarios.
>
> I'd greatly prefer that, I even gave it a shot, but gave up. I'm happy
> to do a pairing session with you or Noah on this one.
>

Definitely. I'd jump in but lets just hypothetically say i've been up
for 23 hours. Hypothetically...

But in all seriousness, yeah, we should get to this. I *really* want
docs to be part of our official procedure and primary concerns. (I
reread that and feel the need to point out I'm not being sarcastic.
Django level docs are something I aspire to).

>
>> There's also the question of making it a soft dep. The doc builds
>> require both perl and Java which is two more languages that we'd
>> require if they're a hard dependency. Once the doc builds are
>> integrated into autotools I don't think this will be a terribly
>> difficult thing to accomplish but its another one of those things I'd
>> like to happen so its not just carried on and hand waved forever.
>
> The current implementation is a soft dependency, if COUCHDB_DOC_JAR_DIR
> isn't defined, the docs aren't built and a message is printed at make
> time.
>

I saw that and its a step in the right direction. But I'd like to see
more of a "test and notify" type approach where we try and build some
small thing and if it fails we say it in the configure output with
hopefully a pointer on why it failed.

>
>> For legal stuff I'm mostly mollified from my reading. Though I think
>> we should also start a thread on legal-discuss (or someone link me to
>> one) about possibly non-ASL2.0 compatible dependencies for building
>> docs (that aren't required to build the code and would be
>> pre-generated for releases so as to not require downstream users to
>> install said deps). I think we're good here but I'm unsure enough that
>> I'd like some supervision on it.
>
> I think we are good on this based on the "soft dependency" rule.
>
> The dependencies and their licenses are:
>
>  Saxon: Mozilla Public License version 1.0
>  Xalan: Apache 2.0 (xalan.apache.org)
>  Xerxes: Apache 2.0 (xerxes.apache.org)
>  xslthl: zlib/libpng
>
> All licenses can be included in source (Apache 2, zlib) or binary
> form (MPL) in a release, which we don't even do. None of the
> binaries "infect" the documentation .html files we'd ship as far
> as I can tell.
>
> But! — I think it is a great idea to present this to legal-discuss@
> and get a second opinion.
>

I glanced at the jar deps and didn't see anything. My real worry is if
one of those Perl modules happens to be GPL or something. I'm *fairly*
certain it doesn't matter since we're obviously not linking and it's a
soft dep for docs. But a quick "We might be wasting your time..."
thread on legal-discuss would make me sleep better.

>
>> Other than that I think it looks good. We should probably take Jan's
>> notes from this thread and put them in share/docs/(README|BUILDING) or
>> something. And make sure the build system references that loudly if
>> things go borkity borkity meatballs.
>
> I hope that is all already in the README :)
>

Ah, may have missed it. I was just thinking about when the build
system prints a big warning like "Unable to build docs." that we have
a "See this thing for more info". I might've been biased by reading
your email and then scanning sources and missed it.

> Cheers
> Jan
> --
>
>
>>
>> On Thu, Jun 21, 2012 at 7:27 AM, Simon Metson <simon@cloudant.com> wrote:
>>> I've been prodding Jan's docs branch this morning. Some successes, some fails.
>>>
>>> * I can't install xsltproc via brew (as in the docs README):
>>>
>>> $ brew install xsltproc
>>> Error: No available formula for xsltproc
>>>
>>>
>>> * Regardless of that I got the docs to build, and made a PDF/bunch of html files.
>>> * I couldn't get this to work with a make of couch itself, the build of couch
crashes:
>>>
>>> /tmp/couch $ ./bin/couchdb
>>> Apache CouchDB 1.3.0a-7f1461e-git (LogLevel=info) is starting.
>>> {"init terminating in do_boot",{{badmatch,{error,{bad_return,{{couch_app,start,[normal,["/tmp/couch/etc/couchdb/default.ini","/tmp/couch/etc/couchdb/local.ini"]]},{'EXIT',{{badmatch,{error,shutdown}},[{couch_server_sup,start_server,1,[{file,"couch_server_sup.erl"},{line,96}]},{application_master,start_it_old,4,[{file,"application_master.erl"},{line,274}]}]}}}}}},[{couch,start,0,[{file,"couch.erl"},{line,18}]},{init,start_it,1,[]},{init,start_em,1,[]}]}}
>>>
>>> Crash dump was written to: erl_crash.dump
>>> init terminating in do_boot ()
>>>
>>> which I assume isn't related to docs.
>>> * did a make clean in both docs and main dir, once I did that the docs build
fails:
>>> SEVERE: Exception
>>> javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException:
"{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:root"! (See position
1110:144)
>>>
>>>
>>> I'm guessing something didn't get cleaned up correctly - I'm going to try a fresh
check out next.
>>>
>>> Where do you want to go with this beyond having it available from futon? Like
I said in Berlin I'm happy to contribute where I can...
>>>
>>>
>>> On Sunday, 17 June 2012 at 14:17, Jan Lehnardt wrote:
>>>
>>>>
>>>> On Jun 17, 2012, at 15:05 , Jan Lehnardt wrote:
>>>>
>>>>>
>>>>> On Jun 17, 2012, at 12:47 , Jan Lehnardt wrote:
>>>>>
>>>>>>
>>>>>> On Jun 17, 2012, at 12:12 , Jan Lehnardt wrote:
>>>>>>
>>>>>>> Same repo, some news:
>>>>>>>
>>>>>>> - updated NOTICE
>>>>>>> - added minimal css styling to make it not look ass
>>>>>>> - made make distcheck pass* (wooo!)
>>>>>>> - linked the per-chapter build in Futon instead of the full-page.**
>>>>>>>
>>>>>>> As far as I can see, this is good to go into master.
>>>>>>
>>>>>> Well, one more thing™: I need to hook this up to `make install`.
>>>>>> I'll try and do this right away.
>>>>>>
>>>>>
>>>>>
>>>>> I got this half done, but I think I will need from you guys.
>>>>>
>>>>> The latest version is still on https://github.com/janl/couchdb/tree/docs
>>>>>
>>>>> If you do
>>>>>
>>>>> $ export COUCHDB_DOC_JAR_DIR=/path/to/doc/jars
>>>>> $ make
>>>>> $ cd share/docs
>>>>> $ make
>>>>> $ cd ../..
>>>>> $ make install
>>>>>
>>>>
>>>>
>>>> actually:
>>>>
>>>> $ cd share/docs
>>>> $ make
>>>> $ cd ../..
>>>> [$ make]
>>>> $ make install
>>>>
>>>> Cheers
>>>> Jan
>>>> --
>>>>
>>>>>
>>>>> The docs get installed properly and the hook up with Futon works just
fine.
>>>>>
>>>>> Obviously, we want `make` in `share/doc` to run as part of the top level
>>>>> make, but I don't know how to hook this up.
>>>>>
>>>>> I tried porting all `Makefiles` in `share/doc` to `Makefile.am (http://Makefile.am)`
like we do
>>>>> elsewhere, but then the docs build system gets confused with paths, I
don't
>>>>> think this is going to work without porting the whole docs build system
to
>>>>> the way CouchDB uses make. An easier way for now would be to treat the
docs
>>>>> build system as a black box that gets started with `make` in share/docs.
>>>>> `make install` for docs is handled in `share/Makefile.am (http://Makefile.am)`.
>>>>>
>>>>> Any help is appreciated!
>>>>> Cheers
>>>>> Jan
>>>>> --
>>>>>
>>>>
>>>>
>>>>
>>>
>>>
>

Mime
View raw message