On Jun 21, 2012, at 16:18 , Paul Davis wrote: > On Thu, Jun 21, 2012 at 8:53 AM, Jan Lehnardt <j...@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 <si...@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 >>>>>> -- >>>>>> >>>>> >>>>> >>>>> >>>> >>>> >>