incubator-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 13:16:37 GMT
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.

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.

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.

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.

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