couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: Docs, second try
Date Thu, 21 Jun 2012 14:35:20 GMT

On Jun 21, 2012, at 16:18 , Paul Davis wrote:

> 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).

+1. Get some hypothetical sleep :)


>>> 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.

Yeah, totally, if we can get this neatly integrated, I'd prefer that!
I just did the simplest thing I could get to work.


>>> 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.

Yup!


>>> 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
-- 



> 
>> 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