You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Jan Lehnardt <ja...@apache.org> on 2012/06/11 22:05:29 UTC
Docs, second try
Hey all,
remember that big commit I made to a new docs branch with all
the .jar files in it and whatnot? Well, I've cleaned it up and
pushed it to GitHub:
https://github.com/janl/couchdb/tree/docs
The README states all prerequisites.
I have ripped all the .jar files out of the repo and put them
in a .tgz up on:
http://people.apache.org/~jan/couchdb/couchdb-doc-jars.tgz
To build the docs go to share/docs and run
$ COUCHDB_DOC_JAR_DIR=/path/to/doc/jars make docs
This is the easiest I could think of for pushing this forward.
I also went through all the other resources in the share/docs
directory and double checked the licensing on all items and
couldn't find anything incompatible. I've still to update
the NOTICE file to make this land on ASF infrastructure, but
I think we are in a good position.
Please check out the branch and give us any feedback, I'd like
to finally finally get this merged soon :)
Cheers
Jan
--
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
On Jun 21, 2012, at 16:18 , Paul Davis wrote:
> On Thu, Jun 21, 2012 at 8:53 AM, Jan Lehnardt <ja...@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
>>>>>> --
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>
Re: Docs, second try
Posted by Paul Davis <pa...@gmail.com>.
On Thu, Jun 21, 2012 at 8:53 AM, Jan Lehnardt <ja...@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 <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
>>>>> --
>>>>>
>>>>
>>>>
>>>>
>>>
>>>
>
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
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.
> 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.
> 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.
> 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 :)
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
>>>> --
>>>>
>>>
>>>
>>>
>>
>>
Re: Docs, second try
Posted by Paul Davis <pa...@gmail.com>.
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 <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
>> > --
>> >
>>
>>
>>
>
>
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
<3
On 21.06.2012, at 22:25, Noah Slater <ns...@tumbolia.org> wrote:
> I am publicly taking ownership of this project, and will run point on it.
>
> I've not contributed code to CouchDB for a while, and my free personal time is scarce, but I am in the best position to do this work. I know Autotools and DocBook very well, and have integrated them in the past.
>
>
>
> On 21 Jun 2012, at 16:25, Simon Metson <si...@cloudant.com> wrote:
>
>> Hi,
>>> This has nothing to do with docbook, we generate HTML and we can link to that in Futon, I don't think we want to generate the Futon-docs part in docbook, but happy to be proven wrong. I think it'd be easer to make a docs.html in futon that keeps the header and sidebar and just shows the /_docs/... link.
>> I'm probably just showing how little I know about docbook ;) (not helped by their documentation wiki being down currently…). If this was sphinx I'd write a theme that would be applied to all the generated html, making it easy to plug into futon (or style for other purposes). I'm assuming we could do the same thing with docbook, though putting the generated content in an iframe is probably quicker (and is what I've just done).
>>>
>>>> What about things like pulling in Dale's jquery.couch.js docs (daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)? (http://daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?)
>>>
>>>
>>> We should definitely consider this, but I think that is out of scope for this particular patch.
>> Agreed, just thinking ahead a bit.
>> Cheers
>> Simon
Re: Docs, second try
Posted by Robert Newson <rn...@apache.org>.
+1 for markdown.
I'm stepping up (with Paul Davis) to get on with the BigCouch merge, which will mean these docs will need a fair amount of editing and expanding. It would be nice if they were in a format that encouraged that.
B.
On 31 Jul 2012, at 03:08, Dave Cottlehuber wrote:
> On 30 July 2012 18:41, Simon Metson <si...@cloudant.com> wrote:
>> Hi,
>> Has this moved on at all? Thinking about it a bit more (off and on)
>> I'm inclined to suggest that DocBook isn't the greatest format. If
>> we stored the docs in markdown it would be easier for people to
>> edit/contribute (they could view the docs and make changes in
>> github without having to compile/install anything). I'm happy to
>> put some cycles into converting whats there to a bunch of
>> markdown. Rendering that in futon is pretty easy too.
>>
>> I can see the benefits of DocBook for writing a book, but I'm not
>> sure that its what's needed here - it seems like using a hammer to
>> crack a nut.
>> Cheers
>> Simon
>
> +1. TL;DR:
>
> Let's focus on the *real* issue: despite having a great working base
> for over 5 months now, the docs contribution barrier is too high for
> even the dev community to make any progress.
>
> I now have a working export of DocBook -> Markdown, using Pandoc[1],
> which can be turned into HTML5, PDFs or ePUBs easily.
>
> Notes/results: https://gist.github.com/3212532#file_readme.md
> If you want epub or PDF, try using this branch:
> https://github.com/dch/couchdb/tree/docs
>
> My next steps:
>
> - check the details (in daytime)
> - document how to add a chapter/section
> - make a list of things to be added to reach 1.2.0 equivalence
> - get stuck in & get helpers
> - sort out CSS & images for futon & standalone viewing
> - integrate build step with autotools
> - get this into 1.3.0
>
> Long Version:
>
> Tonight, I tried to add a simple section to the XML pages, explaining the new
> [vendor] field in default.ini. I gave up after an hour of faffing about.
>
> If I'm not able to drive it, we set the contribution barrier too high methinks.
>
> I then tried installing XML editors and trying to make sense
> of the admittedly awesome couchbase doc structure, and related
> tools. I still failed, I was unable to add a simple chapter, or clarify
> the new [vendor] section in default.ini.
>
> Clearly somebody who *knows* DocBook and XML will be annoyed
> at my incompetence, but so far none of those people have the time
> to move our docs along, and more importantly, nor do most of our
> contributors. I want this in 1.3.0, as a solid baseline for the next
> release with bigcouch included.
>
> The output is not yet perfect, but I believe its workable:
>
> - the structure is right (chapters, headings, links, code)
> - integrating small sections works (merge chapters -> larger doc)
> - images are missing (I was too lazy to copy them in)
> - some tables are not right yet (ditto)
> - I don't have CSS right (ditto)
>
> Let's do the conversion, get the docs into master, and get them
> updated for 1.3. I'm up for it & I'm not waiting for DocBook nirvana
> to arrive, because the current barrier to contribution is simply too high.
>
> Pandoc[1], is a GPL-licensed Haskell library. It's available as a binary
> on pretty much every system we dev on, either in package manager tools
> or via download. And it just works, surprisingly well too, and it's
> fricking FAST. Blazing. DocBook -> HTML5 in seconds, without
> installing FOP, 6 jars, 12 perl modules, and the kitchen sink.
>
> Let's get this off the ground. Please.
>
> A+
> Dave
>
> [1]: http://johnmacfarlane.net/pandoc/
Re: Docs, second try
Posted by Carlton Gibson <ca...@gmail.com>.
On 31 Jul 2012, at 16:01, Robert Newson <rn...@apache.org> wrote:
> I haven't used Sphinx, is it popular?
Sphinx is very popular in the Python world. It's a great tool.
reStructuredText is not much different from Markdown to being.
Re: Docs, second try
Posted by Alexander Shorin <kx...@gmail.com>.
Hi all!
I had some free time to try port docbook docs to sphinx and that's
what I'd done:
http://kxepal.iriscouch.com/docs/1.1/index.html
Currently I'd done 1-9 chapters, some typo fixes and little structure
refactoring and now I have to go work. Others things + term generation
I could try to finish later during lunch at work, if nobody minds.
sources with repo and prebuilded html files if someone needed:
http://kxepal.iriscouch.com/docs/1.1/couchdb-docs.zip
Hope this helps somehow(:
--
,,,^..^,,,
On Wed, Aug 1, 2012 at 5:52 AM, Noah Slater <ns...@tumbolia.org> wrote:
> Sorry guys. Life got in the way, as it does.
>
> As I see it, we have two options:
>
> 1) Pick a source format that can convert to Texinfo. The source format should be easy to EDIT. The Texinfo requirement is so that it hooks in to Autotools. (Which gives us info pages, HTML, PDF, etc, for free.)
>
> 2) Write the docs in HTML.
>
> Has anyone considered option 2?
>
> If you don't think it's possible, or would be complex to edit, see:
>
> https://github.com/oreilly/couchdb-guide/
>
> The only downside to option 2 is that we will have to develop a style guide, and enforce it, if we wish to keep the source clean and readable. (Again, see above.)
>
> I have lots of DocBook experience, and I am still prepared to run point on this. (If you will forgive my previous lack of attention.)
>
> If we can build consensus around which option we want to go with, I can allocate some time upfront to getting the existing stuff imported, converted, and in a state ready to ship.
>
>
>
> On 31 Jul 2012, at 22:22, Benoit Chesneau <bc...@gmail.com> wrote:
>
>> On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>>> I've converted the docs into reST + Sphinx here (via Pandoc):
>>>
>>> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
>>> http://couchdb.readthedocs.org/en/latest/
>>>
>>> This needs a little more reordering and structuring, but I think it
>>> looks pretty good already.
>>>
>>> I'd be happy to work on this more so it'll be a good resource before
>>> the next release.
>>>
>>> Cheers,
>>>
>>> Dirkjan
>>
>> That's awesome. I like it :) Thanks!
>>
>> I guess we could try some custom module later on a second pass, like this one :
>>
>> http://packages.python.org/sphinxcontrib-httpdomain/
>>
>> But current result is enough by itself. I guess we could reuse the
>> makefile provided with sphinx and integrate it in our sources too.
>> Then last piece of work is adding a custom --generate-doc option to
>> autotools :)
>>
>> - benoit
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
Sorry guys! It was literally in bed half asleep when I sent that! ^_^
The RST stuff looks slick as fuck. Are we ready to merge this in to our
main repos? I love it.
Just double checked the Pandoc docs, and we can convert the rst in to
Texinfo.
So, we have two options from here:
- Convert this in to Texinfo, and let Autotools handle info pages, PDF,
PS, etc, or...
- Use Sphinx to generate everything (as it seems to be able to) and just
hook that up to Autotools
Now, I am a hardcore Autotools nut, but I think using Sphinx to convert
into our output formats may yeild the best results, as Sphinx is more
likely to produce consistent formatting across all of them. We can then
just use Autotools to drop the files in to the right places.
So, if we can merge this work in to share/docs, I can hook it in to
Autotools.
(Which should include integration with the build, and installing into
Futon, etc, etc.)
On Wed, Aug 1, 2012 at 5:44 AM, Benoit Chesneau <bc...@gmail.com> wrote:
> On Wednesday, August 1, 2012, Noah Slater wrote:
>
> > Sorry guys. Life got in the way, as it does.
> >
> > As I see it, we have two options:
> >
> > 1) Pick a source format that can convert to Texinfo. The source format
> > should be easy to EDIT. The Texinfo requirement is so that it hooks in to
> > Autotools. (Which gives us info pages, HTML, PDF, etc, for free.)
> >
> > 2) Write the docs in HTML.
> >
> > Has anyone considered option 2?
> >
> > If you don't think it's possible, or would be complex to edit, see:
> >
> > https://github.com/oreilly/couchdb-guide/
> >
> > The only downside to option 2 is that we will have to develop a style
> > guide, and enforce it, if we wish to keep the source clean and readable.
> > (Again, see above.)
> >
> > I have lots of DocBook experience, and I am still prepared to run point
> on
> > this. (If you will forgive my previous lack of attention.)
> >
> > If we can build consensus around which option we want to go with, I can
> > allocate some time upfront to getting the existing stuff imported,
> > converted, and in a state ready to ship.
> >
> >
> >
> >
> i'm confused. Siunds like this mail ignore the current result using
> sphinx.... What do you think about that work? What compared to these 2
> options ?
>
> benoît
>
> > On 31 Jul 2012, at 22:22, Benoit Chesneau <bchesneau@gmail.com
> <javascript:;>>
> > wrote:
> >
> > > On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <dirkjan@ochtman.nl
> <javascript:;>>
> > wrote:
> > >> I've converted the docs into reST + Sphinx here (via Pandoc):
> > >>
> > >> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
> > >> http://couchdb.readthedocs.org/en/latest/
> > >>
> > >> This needs a little more reordering and structuring, but I think it
> > >> looks pretty good already.
> > >>
> > >> I'd be happy to work on this more so it'll be a good resource before
> > >> the next release.
> > >>
> > >> Cheers,
> > >>
> > >> Dirkjan
> > >
> > > That's awesome. I like it :) Thanks!
> > >
> > > I guess we could try some custom module later on a second pass, like
> > this one :
> > >
> > > http://packages.python.org/sphinxcontrib-httpdomain/
> > >
> > > But current result is enough by itself. I guess we could reuse the
> > > makefile provided with sphinx and integrate it in our sources too.
> > > Then last piece of work is adding a custom --generate-doc option to
> > > autotools :)
> > >
> > > - benoit
> >
>
--
NS
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
Dirkjan, please just concentrate on getting the output targets of your
existing Makefile working. (The Makefile I saw when I checked out your
Github repo last.) Don't bother yourself with Autotools. Just get the docs
dir working as if it were a separate concern, and I will take care of
integration.
As for the Git hook and where the docs will live. At this point, I believe
the docs should live at http://apache.org/dist/couchdb/docs/ and I put
provisions in place for this during last release. I believe that part of
the release process should be to upload a static version of the docs for
that release to this directory, like we upload a static release artefact.
Please remember that couchdb.apache.org is a static website. A brochure
page. It was designed, on purpose, to be a single page. And so, the docs
should not live there. (I am unprepared, at this stage, to rethink the
marketing site so soon after we put it in place.) So this site should just
link to the static export of docs, for each version.
I will also take care of this, as I believe it falls under
the release team's responsibility.
On Fri, Aug 3, 2012 at 8:08 AM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Fri, Aug 3, 2012 at 5:47 AM, Benoit Chesneau <bc...@gmail.com>
> wrote:
> > I'm trying to summarize the actions we need to put in place here:
> >
> > 1. create the doc branch , start to track the process of the
> > conversion to make sure we didn't lost an information.
>
> I have a docs branch working on this:
> https://github.com/djco/couchdb/commits/docs
>
> > 2. hack the autotools to handle this makefile and the needed check
>
> I can make a start with that, but Noah will take it further as needed.
>
> > 3. hoock it to git? (can we do that actually on the apache website)
>
> I've set this up for readthedocs.org (hook from my branch, mentioned
> above), we can switch that later.
>
> > Where do we host the doc?
>
> I'll leave that to the committers. readthedocs.org works nicely,
> though, will let you do automatic updating using a hook, and I think
> can do custom domains.
>
> > Where do we place the donated docs?
>
> The consensus in IRC was that they would remain in the repository
> history of the docs branch, but not in new commits once the Sphinx
> conversion is complete.
>
> Cheers,
>
> Dirkjan
>
--
NS
Re: Docs, second try
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Fri, Aug 3, 2012 at 5:47 AM, Benoit Chesneau <bc...@gmail.com> wrote:
> I'm trying to summarize the actions we need to put in place here:
>
> 1. create the doc branch , start to track the process of the
> conversion to make sure we didn't lost an information.
I have a docs branch working on this:
https://github.com/djco/couchdb/commits/docs
> 2. hack the autotools to handle this makefile and the needed check
I can make a start with that, but Noah will take it further as needed.
> 3. hoock it to git? (can we do that actually on the apache website)
I've set this up for readthedocs.org (hook from my branch, mentioned
above), we can switch that later.
> Where do we host the doc?
I'll leave that to the committers. readthedocs.org works nicely,
though, will let you do automatic updating using a hook, and I think
can do custom domains.
> Where do we place the donated docs?
The consensus in IRC was that they would remain in the repository
history of the docs branch, but not in new commits once the Sphinx
conversion is complete.
Cheers,
Dirkjan
Re: Docs, second try
Posted by Robert Newson <ro...@gmail.com>.
The docs should be hosted on https://couchdb.apache.org/ imo.
B.
On 3 Aug 2012, at 04:47, Benoit Chesneau wrote:
> On Wed, Aug 1, 2012 at 2:21 PM, Noah Slater <ns...@tumbolia.org> wrote:
>> That's fine. Just get the Sphinx makefile working enough to generate the
>> docs in the current working directory. Then merge your docs branch to
>> master. At that point, I will convert your makefile into an Autotools
>> makefile, and hook it up with all the right stuff. Sounds like we have
>> consensus, and a tag-team plan. :D
>
>
> I'm trying to summarize the actions we need to put in place here:
>
> 1. create the doc branch , start to track the process of the
> conversion to make sure we didn't lost an information.
> 2. hack the autotools to handle this makefile and the needed check
> 3. hoock it to git? (can we do that actually on the apache website)
>
> Where do we host the doc?
>
> - Do we need to host it on the apache website? Which would imply to
> hack the site generation to make sure the generated docs are landing
> in a folder.
> - Do we hosts them on readthedocs under docs.couchdb.org ?
> - both
>
> Where do we place the donated docs?. Some where speaking to post them
> in a branch, zhich is good imo. But did the donation follow the apache
> process for that?
>
> - benoit
>>
>> On Wed, Aug 1, 2012 at 1:07 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>>
>>> On Wed, Aug 1, 2012 at 2:00 PM, Noah Slater <ns...@tumbolia.org> wrote:
>>>> What is Pytohn nirvana? Is that related to the Sphinx effort I checked
>>> out
>>>> towards the end of this thread?
>>>
>>> Sphinx is written in Python, but I'm not sure why Dave mentioned the
>>> Python nirvana. You don't need to write any Python to improve Sphinx
>>> docs, just installing some Python-based tools to turn them into HTML
>>> or any of other output formats.
>>>
>>>> I think once the docs are converted to RST and the Sphinx work looks
>>> okay,
>>>> we should merge this into master, and I am offering to take over from
>>>> there. I will happily integrate this into the build system, hook it up
>>> with
>>>> Futon, update the README files, etc.
>>>>
>>>> What is standing between here and there?
>>>>
>>>> What is there left to do before we can get the Sphinx work into master
>>> for
>>>> further iteration?
>>>
>>> The conversion from DocBook to Sphinx isn't perfect, so it needs a bit
>>> of tweaking to fix up links and some minor syntax issues. I'm happy to
>>> work on that; I think it makes sense to keep this work on the docs
>>> branch for a bit longer while these small issues get fixed.
>>>
>>> I'm also happy to do further work after that (though I may not be the
>>> best person to work on autotools integration, other than calling the
>>> Sphinx Makefile from one of the other Makefiles).
>>>
>>> Cheers,
>>>
>>> Dirkjan
>>>
>>>>
>>>> On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman <di...@ochtman.nl>
>>> wrote:
>>>>
>>>>> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <da...@muse.net.nz>
>>> wrote:
>>>>>> Do we have a concensus now to go for RST & python nirvana?
>>>>>
>>>>> If we do, a proposed plan forward, with Dave and Robert N.:
>>>>>
>>>>> - Keep the docs branch as it is, with DocBook docs
>>>>> - Iterate on the Sphinx docs in the docs branch (for example based on my
>>>>> csets)
>>>>> - When everything has properly been converted to Sphinx, remove DocBook
>>>>> files
>>>>> - At this point, merge docs into master and do further improvement
>>>>>
>>>>> This means the DocBook version is safely in repository history for
>>>>> archival purposes. Sphinx building can easily be integrated into
>>>>> Makefiles, we'll also need to update some READMEs etc to document
>>>>> Sphinx dependencies. We should probably not wait until the docs are
>>>>> perfect before merging into master, but make sure everything from the
>>>>> DocBook version is in there.
>>>>>
>>>>> I'll note that I think the pace of movement around the Sphinx stuff
>>>>> indicates that this significantly helps contribution to the docs, so I
>>>>> think this would be a great way to move forward.
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Dirkjan
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> NS
>>>
>>
>>
>>
>> --
>> NS
Re: Docs, second try
Posted by Benoit Chesneau <bc...@gmail.com>.
On Wed, Aug 1, 2012 at 2:21 PM, Noah Slater <ns...@tumbolia.org> wrote:
> That's fine. Just get the Sphinx makefile working enough to generate the
> docs in the current working directory. Then merge your docs branch to
> master. At that point, I will convert your makefile into an Autotools
> makefile, and hook it up with all the right stuff. Sounds like we have
> consensus, and a tag-team plan. :D
I'm trying to summarize the actions we need to put in place here:
1. create the doc branch , start to track the process of the
conversion to make sure we didn't lost an information.
2. hack the autotools to handle this makefile and the needed check
3. hoock it to git? (can we do that actually on the apache website)
Where do we host the doc?
- Do we need to host it on the apache website? Which would imply to
hack the site generation to make sure the generated docs are landing
in a folder.
- Do we hosts them on readthedocs under docs.couchdb.org ?
- both
Where do we place the donated docs?. Some where speaking to post them
in a branch, zhich is good imo. But did the donation follow the apache
process for that?
- benoit
>
> On Wed, Aug 1, 2012 at 1:07 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>
>> On Wed, Aug 1, 2012 at 2:00 PM, Noah Slater <ns...@tumbolia.org> wrote:
>> > What is Pytohn nirvana? Is that related to the Sphinx effort I checked
>> out
>> > towards the end of this thread?
>>
>> Sphinx is written in Python, but I'm not sure why Dave mentioned the
>> Python nirvana. You don't need to write any Python to improve Sphinx
>> docs, just installing some Python-based tools to turn them into HTML
>> or any of other output formats.
>>
>> > I think once the docs are converted to RST and the Sphinx work looks
>> okay,
>> > we should merge this into master, and I am offering to take over from
>> > there. I will happily integrate this into the build system, hook it up
>> with
>> > Futon, update the README files, etc.
>> >
>> > What is standing between here and there?
>> >
>> > What is there left to do before we can get the Sphinx work into master
>> for
>> > further iteration?
>>
>> The conversion from DocBook to Sphinx isn't perfect, so it needs a bit
>> of tweaking to fix up links and some minor syntax issues. I'm happy to
>> work on that; I think it makes sense to keep this work on the docs
>> branch for a bit longer while these small issues get fixed.
>>
>> I'm also happy to do further work after that (though I may not be the
>> best person to work on autotools integration, other than calling the
>> Sphinx Makefile from one of the other Makefiles).
>>
>> Cheers,
>>
>> Dirkjan
>>
>> >
>> > On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman <di...@ochtman.nl>
>> wrote:
>> >
>> >> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <da...@muse.net.nz>
>> wrote:
>> >> > Do we have a concensus now to go for RST & python nirvana?
>> >>
>> >> If we do, a proposed plan forward, with Dave and Robert N.:
>> >>
>> >> - Keep the docs branch as it is, with DocBook docs
>> >> - Iterate on the Sphinx docs in the docs branch (for example based on my
>> >> csets)
>> >> - When everything has properly been converted to Sphinx, remove DocBook
>> >> files
>> >> - At this point, merge docs into master and do further improvement
>> >>
>> >> This means the DocBook version is safely in repository history for
>> >> archival purposes. Sphinx building can easily be integrated into
>> >> Makefiles, we'll also need to update some READMEs etc to document
>> >> Sphinx dependencies. We should probably not wait until the docs are
>> >> perfect before merging into master, but make sure everything from the
>> >> DocBook version is in there.
>> >>
>> >> I'll note that I think the pace of movement around the Sphinx stuff
>> >> indicates that this significantly helps contribution to the docs, so I
>> >> think this would be a great way to move forward.
>> >>
>> >> Cheers,
>> >>
>> >> Dirkjan
>> >>
>> >
>> >
>> >
>> > --
>> > NS
>>
>
>
>
> --
> NS
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
That's fine. Just get the Sphinx makefile working enough to generate the
docs in the current working directory. Then merge your docs branch to
master. At that point, I will convert your makefile into an Autotools
makefile, and hook it up with all the right stuff. Sounds like we have
consensus, and a tag-team plan. :D
On Wed, Aug 1, 2012 at 1:07 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Wed, Aug 1, 2012 at 2:00 PM, Noah Slater <ns...@tumbolia.org> wrote:
> > What is Pytohn nirvana? Is that related to the Sphinx effort I checked
> out
> > towards the end of this thread?
>
> Sphinx is written in Python, but I'm not sure why Dave mentioned the
> Python nirvana. You don't need to write any Python to improve Sphinx
> docs, just installing some Python-based tools to turn them into HTML
> or any of other output formats.
>
> > I think once the docs are converted to RST and the Sphinx work looks
> okay,
> > we should merge this into master, and I am offering to take over from
> > there. I will happily integrate this into the build system, hook it up
> with
> > Futon, update the README files, etc.
> >
> > What is standing between here and there?
> >
> > What is there left to do before we can get the Sphinx work into master
> for
> > further iteration?
>
> The conversion from DocBook to Sphinx isn't perfect, so it needs a bit
> of tweaking to fix up links and some minor syntax issues. I'm happy to
> work on that; I think it makes sense to keep this work on the docs
> branch for a bit longer while these small issues get fixed.
>
> I'm also happy to do further work after that (though I may not be the
> best person to work on autotools integration, other than calling the
> Sphinx Makefile from one of the other Makefiles).
>
> Cheers,
>
> Dirkjan
>
> >
> > On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman <di...@ochtman.nl>
> wrote:
> >
> >> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <da...@muse.net.nz>
> wrote:
> >> > Do we have a concensus now to go for RST & python nirvana?
> >>
> >> If we do, a proposed plan forward, with Dave and Robert N.:
> >>
> >> - Keep the docs branch as it is, with DocBook docs
> >> - Iterate on the Sphinx docs in the docs branch (for example based on my
> >> csets)
> >> - When everything has properly been converted to Sphinx, remove DocBook
> >> files
> >> - At this point, merge docs into master and do further improvement
> >>
> >> This means the DocBook version is safely in repository history for
> >> archival purposes. Sphinx building can easily be integrated into
> >> Makefiles, we'll also need to update some READMEs etc to document
> >> Sphinx dependencies. We should probably not wait until the docs are
> >> perfect before merging into master, but make sure everything from the
> >> DocBook version is in there.
> >>
> >> I'll note that I think the pace of movement around the Sphinx stuff
> >> indicates that this significantly helps contribution to the docs, so I
> >> think this would be a great way to move forward.
> >>
> >> Cheers,
> >>
> >> Dirkjan
> >>
> >
> >
> >
> > --
> > NS
>
--
NS
Re: Docs, second try
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Wed, Aug 1, 2012 at 2:00 PM, Noah Slater <ns...@tumbolia.org> wrote:
> What is Pytohn nirvana? Is that related to the Sphinx effort I checked out
> towards the end of this thread?
Sphinx is written in Python, but I'm not sure why Dave mentioned the
Python nirvana. You don't need to write any Python to improve Sphinx
docs, just installing some Python-based tools to turn them into HTML
or any of other output formats.
> I think once the docs are converted to RST and the Sphinx work looks okay,
> we should merge this into master, and I am offering to take over from
> there. I will happily integrate this into the build system, hook it up with
> Futon, update the README files, etc.
>
> What is standing between here and there?
>
> What is there left to do before we can get the Sphinx work into master for
> further iteration?
The conversion from DocBook to Sphinx isn't perfect, so it needs a bit
of tweaking to fix up links and some minor syntax issues. I'm happy to
work on that; I think it makes sense to keep this work on the docs
branch for a bit longer while these small issues get fixed.
I'm also happy to do further work after that (though I may not be the
best person to work on autotools integration, other than calling the
Sphinx Makefile from one of the other Makefiles).
Cheers,
Dirkjan
>
> On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>
>> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <da...@muse.net.nz> wrote:
>> > Do we have a concensus now to go for RST & python nirvana?
>>
>> If we do, a proposed plan forward, with Dave and Robert N.:
>>
>> - Keep the docs branch as it is, with DocBook docs
>> - Iterate on the Sphinx docs in the docs branch (for example based on my
>> csets)
>> - When everything has properly been converted to Sphinx, remove DocBook
>> files
>> - At this point, merge docs into master and do further improvement
>>
>> This means the DocBook version is safely in repository history for
>> archival purposes. Sphinx building can easily be integrated into
>> Makefiles, we'll also need to update some READMEs etc to document
>> Sphinx dependencies. We should probably not wait until the docs are
>> perfect before merging into master, but make sure everything from the
>> DocBook version is in there.
>>
>> I'll note that I think the pace of movement around the Sphinx stuff
>> indicates that this significantly helps contribution to the docs, so I
>> think this would be a great way to move forward.
>>
>> Cheers,
>>
>> Dirkjan
>>
>
>
>
> --
> NS
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
Dirkjan,
Texinfo is important because we are using Autotools, and it expects texinfo
so it can install info pages. Autotools comes with a toolchain which will
convert texinfo into other formats for you, for free. The user doesn't need
anything installed locally on their machine. This is why I listed it as a
requirement for the docs solution we pick. Fortunately, Sphinx satisfies
this, which is why I am pleased.
What is Pytohn nirvana? Is that related to the Sphinx effort I checked out
towards the end of this thread?
I think once the docs are converted to RST and the Sphinx work looks okay,
we should merge this into master, and I am offering to take over from
there. I will happily integrate this into the build system, hook it up with
Futon, update the README files, etc.
What is standing between here and there?
What is there left to do before we can get the Sphinx work into master for
further iteration?
On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > Do we have a concensus now to go for RST & python nirvana?
>
> If we do, a proposed plan forward, with Dave and Robert N.:
>
> - Keep the docs branch as it is, with DocBook docs
> - Iterate on the Sphinx docs in the docs branch (for example based on my
> csets)
> - When everything has properly been converted to Sphinx, remove DocBook
> files
> - At this point, merge docs into master and do further improvement
>
> This means the DocBook version is safely in repository history for
> archival purposes. Sphinx building can easily be integrated into
> Makefiles, we'll also need to update some READMEs etc to document
> Sphinx dependencies. We should probably not wait until the docs are
> perfect before merging into master, but make sure everything from the
> DocBook version is in there.
>
> I'll note that I think the pace of movement around the Sphinx stuff
> indicates that this significantly helps contribution to the docs, so I
> think this would be a great way to move forward.
>
> Cheers,
>
> Dirkjan
>
--
NS
Re: Docs, second try
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <da...@muse.net.nz> wrote:
> Do we have a concensus now to go for RST & python nirvana?
If we do, a proposed plan forward, with Dave and Robert N.:
- Keep the docs branch as it is, with DocBook docs
- Iterate on the Sphinx docs in the docs branch (for example based on my csets)
- When everything has properly been converted to Sphinx, remove DocBook files
- At this point, merge docs into master and do further improvement
This means the DocBook version is safely in repository history for
archival purposes. Sphinx building can easily be integrated into
Makefiles, we'll also need to update some READMEs etc to document
Sphinx dependencies. We should probably not wait until the docs are
perfect before merging into master, but make sure everything from the
DocBook version is in there.
I'll note that I think the pace of movement around the Sphinx stuff
indicates that this significantly helps contribution to the docs, so I
think this would be a great way to move forward.
Cheers,
Dirkjan
Re: Docs, second try
Posted by Dave Cottlehuber <da...@muse.net.nz>.
snip, hopefully a summary.
Situation:
Our docs are sucky, fragmented and what there is needs some attention
(wiki, couchbase, guide).
Couchbase has kindly donated DocBook[1] format API docs, and the tools
to manage that. Woot!
We don't have a clear understanding of what we are trying to produce
as an end result.
In order of importance:
1. docbook format is a *perceived* barrier to contribution.
After Dale prodded me I got it working properly & am adding notes[2] on adding:
- chapters (separate file)
- lists
- code sections
- references (incl cross chapter)
- tables
DocBook is *very* wordy but any decent editor with <>/ tab completion,
or zen coding will work.
It's trivial to convert snippets of other formats back to DocBook
using pandoc[3] or your tool of choice.
Would using DB *stop* any of the committers?
2. A clear list of output formats, and desired doc functionality is
required before bikeshedding on tools. I think this list is:
2.1 MUST output to HTML to embed in the source, and onto couchdb.apache.org site
2.2 MUST support chapters, sections, lists (numbered & normal), url
refs (html links), code blocks, images, and tables
2.3 OPTIONAL syntax highlighting of code & JSON
Markdown doesn't properly support 2.2.
RST & DocBook do.
RST does provide 2.3 syntax highlighting from what I can see. DocBook
probably could too but it's not obvious how.
3. Who's doing the work & where?
3.1 enabling community contribution is a MUST, in fact THE MUST DO TOP PRIORITY.
3.2 the community SHOULD easily be able to edit docs on github or
their own git fork easily
3.3 The bulk of documentation changes is going to be done by
committers over time
3.4 the toolchain should be integratable into a normal make
checks/make dist cycle on our supported platforms.
- markdown and .rst are supported on github in some form, which I
think is really important for facilitating easy community
contributions
- there is a clear preference to using .rst in the python dev
community, and the tooling appears simpler
- docbook can do anything** if you have the time & expertise.
- since my export to rst last night, we have already 3 beautiful
examples of how rst can simplify getting stuff done:
- editing (assuming you have repo access)
https://github.com/djco/couchdb/blob/docs/share/docs/sphinx-docs/intro.rst
- reading via sphinx & read the docs:
http://couchdb.readthedocs.org/en/latest/replication.html
- embedded as a couch "app" http://kxepal.iriscouch.com/docs/1.1/index.html
TL;DR:
the only major objections against DocBook are:
- syntax is wordy but manageable
- toolchain is not perfect
But overall, .rst is the way to go, because:
- we'll end up with more documentation as a result
- good community engagement for tooling & using it
- it seems to meet the functional requirements
- it can be set up as a github repo to enable a wider pool of folk to contribute
- AFAICT if reqd it could roundtrip to DocBook if needed
Either way, whether in XML or RST I have enough bits to do what I was
planning to do. Thanks Jan & Noah & others who got us to this point
(I'll graciously overlook him mentioning texinfo and postscript).
Do we have a concensus now to go for RST & python nirvana?
[1]: http://wiki.apache.org/couchdb/Documentation
[2]: https://github.com/dch/couchdb/tree/docs/share/docs/
[3]: http://johnmacfarlane.net/pandoc/try
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
(For reference, Benoît, Sphinx happily satisfies option 1.)
On Wed, Aug 1, 2012 at 5:44 AM, Benoit Chesneau <bc...@gmail.com> wrote:
> On Wednesday, August 1, 2012, Noah Slater wrote:
>
> > Sorry guys. Life got in the way, as it does.
> >
> > As I see it, we have two options:
> >
> > 1) Pick a source format that can convert to Texinfo. The source format
> > should be easy to EDIT. The Texinfo requirement is so that it hooks in to
> > Autotools. (Which gives us info pages, HTML, PDF, etc, for free.)
> >
> > 2) Write the docs in HTML.
> >
> > Has anyone considered option 2?
> >
> > If you don't think it's possible, or would be complex to edit, see:
> >
> > https://github.com/oreilly/couchdb-guide/
> >
> > The only downside to option 2 is that we will have to develop a style
> > guide, and enforce it, if we wish to keep the source clean and readable.
> > (Again, see above.)
> >
> > I have lots of DocBook experience, and I am still prepared to run point
> on
> > this. (If you will forgive my previous lack of attention.)
> >
> > If we can build consensus around which option we want to go with, I can
> > allocate some time upfront to getting the existing stuff imported,
> > converted, and in a state ready to ship.
> >
> >
> >
> >
> i'm confused. Siunds like this mail ignore the current result using
> sphinx.... What do you think about that work? What compared to these 2
> options ?
>
> benoît
>
> > On 31 Jul 2012, at 22:22, Benoit Chesneau <bchesneau@gmail.com
> <javascript:;>>
> > wrote:
> >
> > > On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <dirkjan@ochtman.nl
> <javascript:;>>
> > wrote:
> > >> I've converted the docs into reST + Sphinx here (via Pandoc):
> > >>
> > >> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
> > >> http://couchdb.readthedocs.org/en/latest/
> > >>
> > >> This needs a little more reordering and structuring, but I think it
> > >> looks pretty good already.
> > >>
> > >> I'd be happy to work on this more so it'll be a good resource before
> > >> the next release.
> > >>
> > >> Cheers,
> > >>
> > >> Dirkjan
> > >
> > > That's awesome. I like it :) Thanks!
> > >
> > > I guess we could try some custom module later on a second pass, like
> > this one :
> > >
> > > http://packages.python.org/sphinxcontrib-httpdomain/
> > >
> > > But current result is enough by itself. I guess we could reuse the
> > > makefile provided with sphinx and integrate it in our sources too.
> > > Then last piece of work is adding a custom --generate-doc option to
> > > autotools :)
> > >
> > > - benoit
> >
>
--
NS
Re: Docs, second try
Posted by Benoit Chesneau <bc...@gmail.com>.
On Wednesday, August 1, 2012, Noah Slater wrote:
> Sorry guys. Life got in the way, as it does.
>
> As I see it, we have two options:
>
> 1) Pick a source format that can convert to Texinfo. The source format
> should be easy to EDIT. The Texinfo requirement is so that it hooks in to
> Autotools. (Which gives us info pages, HTML, PDF, etc, for free.)
>
> 2) Write the docs in HTML.
>
> Has anyone considered option 2?
>
> If you don't think it's possible, or would be complex to edit, see:
>
> https://github.com/oreilly/couchdb-guide/
>
> The only downside to option 2 is that we will have to develop a style
> guide, and enforce it, if we wish to keep the source clean and readable.
> (Again, see above.)
>
> I have lots of DocBook experience, and I am still prepared to run point on
> this. (If you will forgive my previous lack of attention.)
>
> If we can build consensus around which option we want to go with, I can
> allocate some time upfront to getting the existing stuff imported,
> converted, and in a state ready to ship.
>
>
>
>
i'm confused. Siunds like this mail ignore the current result using
sphinx.... What do you think about that work? What compared to these 2
options ?
benoît
> On 31 Jul 2012, at 22:22, Benoit Chesneau <bchesneau@gmail.com<javascript:;>>
> wrote:
>
> > On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <dirkjan@ochtman.nl<javascript:;>>
> wrote:
> >> I've converted the docs into reST + Sphinx here (via Pandoc):
> >>
> >> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
> >> http://couchdb.readthedocs.org/en/latest/
> >>
> >> This needs a little more reordering and structuring, but I think it
> >> looks pretty good already.
> >>
> >> I'd be happy to work on this more so it'll be a good resource before
> >> the next release.
> >>
> >> Cheers,
> >>
> >> Dirkjan
> >
> > That's awesome. I like it :) Thanks!
> >
> > I guess we could try some custom module later on a second pass, like
> this one :
> >
> > http://packages.python.org/sphinxcontrib-httpdomain/
> >
> > But current result is enough by itself. I guess we could reuse the
> > makefile provided with sphinx and integrate it in our sources too.
> > Then last piece of work is adding a custom --generate-doc option to
> > autotools :)
> >
> > - benoit
>
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
Sorry guys. Life got in the way, as it does.
As I see it, we have two options:
1) Pick a source format that can convert to Texinfo. The source format should be easy to EDIT. The Texinfo requirement is so that it hooks in to Autotools. (Which gives us info pages, HTML, PDF, etc, for free.)
2) Write the docs in HTML.
Has anyone considered option 2?
If you don't think it's possible, or would be complex to edit, see:
https://github.com/oreilly/couchdb-guide/
The only downside to option 2 is that we will have to develop a style guide, and enforce it, if we wish to keep the source clean and readable. (Again, see above.)
I have lots of DocBook experience, and I am still prepared to run point on this. (If you will forgive my previous lack of attention.)
If we can build consensus around which option we want to go with, I can allocate some time upfront to getting the existing stuff imported, converted, and in a state ready to ship.
On 31 Jul 2012, at 22:22, Benoit Chesneau <bc...@gmail.com> wrote:
> On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>> I've converted the docs into reST + Sphinx here (via Pandoc):
>>
>> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
>> http://couchdb.readthedocs.org/en/latest/
>>
>> This needs a little more reordering and structuring, but I think it
>> looks pretty good already.
>>
>> I'd be happy to work on this more so it'll be a good resource before
>> the next release.
>>
>> Cheers,
>>
>> Dirkjan
>
> That's awesome. I like it :) Thanks!
>
> I guess we could try some custom module later on a second pass, like this one :
>
> http://packages.python.org/sphinxcontrib-httpdomain/
>
> But current result is enough by itself. I guess we could reuse the
> makefile provided with sphinx and integrate it in our sources too.
> Then last piece of work is adding a custom --generate-doc option to
> autotools :)
>
> - benoit
Re: Docs, second try
Posted by Benoit Chesneau <bc...@gmail.com>.
On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> I've converted the docs into reST + Sphinx here (via Pandoc):
>
> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
> http://couchdb.readthedocs.org/en/latest/
>
> This needs a little more reordering and structuring, but I think it
> looks pretty good already.
>
> I'd be happy to work on this more so it'll be a good resource before
> the next release.
>
> Cheers,
>
> Dirkjan
That's awesome. I like it :) Thanks!
I guess we could try some custom module later on a second pass, like this one :
http://packages.python.org/sphinxcontrib-httpdomain/
But current result is enough by itself. I guess we could reuse the
makefile provided with sphinx and integrate it in our sources too.
Then last piece of work is adding a custom --generate-doc option to
autotools :)
- benoit
Re: Docs, second try
Posted by Simon Metson <si...@cloudant.com>.
That's superb Dirkjan - good job!
On Tuesday, 31 July 2012 at 21:23, Dirkjan Ochtman wrote:
> I've converted the docs into reST + Sphinx here (via Pandoc):
>
> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
> http://couchdb.readthedocs.org/en/latest/
>
> This needs a little more reordering and structuring, but I think it
> looks pretty good already.
>
> I'd be happy to work on this more so it'll be a good resource before
> the next release.
>
> Cheers,
>
> Dirkjan
Re: Docs, second try
Posted by Robert Newson <rn...@apache.org>.
I'm liking what I see, awesome work everyone. Can someone help outline what it takes to have this on master?
For me, it's the .rst files under (say) and the commands to build the output html incorporated into our build system.
B.
On 31 Jul 2012, at 21:23, Dirkjan Ochtman wrote:
> I've converted the docs into reST + Sphinx here (via Pandoc):
>
> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
> http://couchdb.readthedocs.org/en/latest/
>
> This needs a little more reordering and structuring, but I think it
> looks pretty good already.
>
> I'd be happy to work on this more so it'll be a good resource before
> the next release.
>
> Cheers,
>
> Dirkjan
Re: Docs, second try
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
I've converted the docs into reST + Sphinx here (via Pandoc):
https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
http://couchdb.readthedocs.org/en/latest/
This needs a little more reordering and structuring, but I think it
looks pretty good already.
I'd be happy to work on this more so it'll be a good resource before
the next release.
Cheers,
Dirkjan
Re: Docs, second try
Posted by Simon Metson <si...@cloudant.com>.
python + sphinx http://sphinx.pocoo.org/
On Tuesday, 31 July 2012 at 16:29, Robert Newson wrote:
>
> Benoit, what sort of effort would be involved in that switch? Am I right that the toolchain for building the docs would be wholly Python?
>
> B.
>
> On 31 Jul 2012, at 15:38, Dirkjan Ochtman wrote:
>
> > On Tue, Jul 31, 2012 at 4:01 PM, Robert Newson <rnewson@apache.org (mailto:rnewson@apache.org)> wrote:
> > > Those are all good points, thanks. I haven't used Sphinx, is it popular? Are there any other choices?
> >
> >
> > It's quite popular. Look at readthedocs.org (http://readthedocs.org) (free Sphinx hosting) or
> > the Python documentation for some examples.
> >
> > Using Sphinx/reST would definitely make it easier for me to finally
> > contribute more to CouchDB, whereas DocBook would definitely not.
> >
> > Cheers,
> >
> > Dirkjan
Re: Docs, second try
Posted by Robert Newson <rn...@apache.org>.
Benoit, what sort of effort would be involved in that switch? Am I right that the toolchain for building the docs would be wholly Python?
B.
On 31 Jul 2012, at 15:38, Dirkjan Ochtman wrote:
> On Tue, Jul 31, 2012 at 4:01 PM, Robert Newson <rn...@apache.org> wrote:
>> Those are all good points, thanks. I haven't used Sphinx, is it popular? Are there any other choices?
>
> It's quite popular. Look at readthedocs.org (free Sphinx hosting) or
> the Python documentation for some examples.
>
> Using Sphinx/reST would definitely make it easier for me to finally
> contribute more to CouchDB, whereas DocBook would definitely not.
>
> Cheers,
>
> Dirkjan
Re: Docs, second try
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Tue, Jul 31, 2012 at 4:01 PM, Robert Newson <rn...@apache.org> wrote:
> Those are all good points, thanks. I haven't used Sphinx, is it popular? Are there any other choices?
It's quite popular. Look at readthedocs.org (free Sphinx hosting) or
the Python documentation for some examples.
Using Sphinx/reST would definitely make it easier for me to finally
contribute more to CouchDB, whereas DocBook would definitely not.
Cheers,
Dirkjan
Re: Docs, second try
Posted by Robert Newson <rn...@apache.org>.
Those are all good points, thanks. I haven't used Sphinx, is it popular? Are there any other choices?
Does this decision block getting the current work onto the master branch? My main concern with the donated documentation is not with the DocBook format itself (I quite like it, but I'd switch in a heartbeat if some other format would encourage more contributions) but the toolchain needed to build it. Last I looked, and forgive me if this has changed, there was quite a bit of work (and a JVM) to build the docs. I wouldn't block the merge to trunk on that basis, but I would probably spend some time to simplify it once it did.
Can we merge what we have into master today and address these problems together within the code base? In the absolute worst case, we can remove it again for a release, but we could leave these on the side forever while we mull over these issues.
B.
On 31 Jul 2012, at 14:28, Benoit Chesneau wrote:
> On Tue, Jul 31, 2012 at 3:22 PM, Robert Newson <rn...@apache.org> wrote:
>>
>> I dislike a veto without an adequate reason. Can you make your objections explicit? What can't we do (that we need) with Markdown?
>
> I gave some:
>>> [..] There is no real doc system in markdown which will
>>> force to write another script and we will lost some features given by
>>> docbook (linking, references...)
>>>
>
> linking, automatic references, templating. specific section markups ...
> the need to write this tool to generate the doc while we could reuse a
> widely used tool wich is important for me. Also with sphinx you could
> still generate a PDF or event an ebook which is imo important for
> those who want to consult the doc offline.
>
> - benoît
Re: Docs, second try
Posted by Benoit Chesneau <bc...@gmail.com>.
On Tue, Jul 31, 2012 at 3:28 PM, Benoit Chesneau <bc...@gmail.com> wrote:
> On Tue, Jul 31, 2012 at 3:22 PM, Robert Newson <rn...@apache.org> wrote:
>>
>> I dislike a veto without an adequate reason. Can you make your objections explicit? What can't we do (that we need) with Markdown?
>
> I gave some:
>>>[..] There is no real doc system in markdown which will
>>> force to write another script and we will lost some features given by
>>> docbook (linking, references...)
>>>
>
> linking, automatic references, templating. specific section markups ...
> the need to write this tool to generate the doc while we could reuse a
> widely used tool wich is important for me. Also with sphinx you could
> still generate a PDF or event an ebook which is imo important for
> those who want to consult the doc offline.
>
> - benoît
To be clear, this not about markdown, this is more because there I
don't know any good documentation tool using this format. If some
exist, then let's go, but I think we should try to use the tool most
know to encourage people to help us to improve and write the
documentation.
- benoit
Re: Docs, second try
Posted by Benoit Chesneau <bc...@gmail.com>.
On Tue, Jul 31, 2012 at 3:22 PM, Robert Newson <rn...@apache.org> wrote:
>
> I dislike a veto without an adequate reason. Can you make your objections explicit? What can't we do (that we need) with Markdown?
I gave some:
>>[..] There is no real doc system in markdown which will
>> force to write another script and we will lost some features given by
>> docbook (linking, references...)
>>
linking, automatic references, templating. specific section markups ...
the need to write this tool to generate the doc while we could reuse a
widely used tool wich is important for me. Also with sphinx you could
still generate a PDF or event an ebook which is imo important for
those who want to consult the doc offline.
- benoît
Re: Docs, second try
Posted by Robert Newson <rn...@apache.org>.
I dislike a veto without an adequate reason. Can you make your objections explicit? What can't we do (that we need) with Markdown?
B.
On 31 Jul 2012, at 13:55, Benoit Chesneau wrote:
> -1 on markdown. There is no real doc system in markdown which will
> force to write another script and we will lost some features given by
> docbook (linking, references...)
>
> If we want to move from docbook I would strongly suggest to go for
> sphinx doc [1] in ReStructuredText. Also sphix is a supported tools
> used even in non python systems. db2rsy [2] can be used to convert
> the docbook files.
>
> - benoit
>
> [1] http://sphinx.pocoo.org/
> [2] http://code.google.com/p/db2rst/
>
> On Tue, Jul 31, 2012 at 4:08 AM, Dave Cottlehuber <da...@muse.net.nz> wrote:
>> On 30 July 2012 18:41, Simon Metson <si...@cloudant.com> wrote:
>>> Hi,
>>> Has this moved on at all? Thinking about it a bit more (off and on)
>>> I'm inclined to suggest that DocBook isn't the greatest format. If
>>> we stored the docs in markdown it would be easier for people to
>>> edit/contribute (they could view the docs and make changes in
>>> github without having to compile/install anything). I'm happy to
>>> put some cycles into converting whats there to a bunch of
>>> markdown. Rendering that in futon is pretty easy too.
>>>
>>> I can see the benefits of DocBook for writing a book, but I'm not
>>> sure that its what's needed here - it seems like using a hammer to
>>> crack a nut.
>>> Cheers
>>> Simon
>>
>> +1. TL;DR:
>>
>> Let's focus on the *real* issue: despite having a great working base
>> for over 5 months now, the docs contribution barrier is too high for
>> even the dev community to make any progress.
>>
>> I now have a working export of DocBook -> Markdown, using Pandoc[1],
>> which can be turned into HTML5, PDFs or ePUBs easily.
>>
>> Notes/results: https://gist.github.com/3212532#file_readme.md
>> If you want epub or PDF, try using this branch:
>> https://github.com/dch/couchdb/tree/docs
>>
>> My next steps:
>>
>> - check the details (in daytime)
>> - document how to add a chapter/section
>> - make a list of things to be added to reach 1.2.0 equivalence
>> - get stuck in & get helpers
>> - sort out CSS & images for futon & standalone viewing
>> - integrate build step with autotools
>> - get this into 1.3.0
>>
>> Long Version:
>>
>> Tonight, I tried to add a simple section to the XML pages, explaining the new
>> [vendor] field in default.ini. I gave up after an hour of faffing about.
>>
>> If I'm not able to drive it, we set the contribution barrier too high methinks.
>>
>> I then tried installing XML editors and trying to make sense
>> of the admittedly awesome couchbase doc structure, and related
>> tools. I still failed, I was unable to add a simple chapter, or clarify
>> the new [vendor] section in default.ini.
>>
>> Clearly somebody who *knows* DocBook and XML will be annoyed
>> at my incompetence, but so far none of those people have the time
>> to move our docs along, and more importantly, nor do most of our
>> contributors. I want this in 1.3.0, as a solid baseline for the next
>> release with bigcouch included.
>>
>> The output is not yet perfect, but I believe its workable:
>>
>> - the structure is right (chapters, headings, links, code)
>> - integrating small sections works (merge chapters -> larger doc)
>> - images are missing (I was too lazy to copy them in)
>> - some tables are not right yet (ditto)
>> - I don't have CSS right (ditto)
>>
>> Let's do the conversion, get the docs into master, and get them
>> updated for 1.3. I'm up for it & I'm not waiting for DocBook nirvana
>> to arrive, because the current barrier to contribution is simply too high.
>>
>> Pandoc[1], is a GPL-licensed Haskell library. It's available as a binary
>> on pretty much every system we dev on, either in package manager tools
>> or via download. And it just works, surprisingly well too, and it's
>> fricking FAST. Blazing. DocBook -> HTML5 in seconds, without
>> installing FOP, 6 jars, 12 perl modules, and the kitchen sink.
>>
>> Let's get this off the ground. Please.
>>
>> A+
>> Dave
>>
>> [1]: http://johnmacfarlane.net/pandoc/
Re: Docs, second try
Posted by Benoit Chesneau <bc...@gmail.com>.
-1 on markdown. There is no real doc system in markdown which will
force to write another script and we will lost some features given by
docbook (linking, references...)
If we want to move from docbook I would strongly suggest to go for
sphinx doc [1] in ReStructuredText. Also sphix is a supported tools
used even in non python systems. db2rsy [2] can be used to convert
the docbook files.
- benoit
[1] http://sphinx.pocoo.org/
[2] http://code.google.com/p/db2rst/
On Tue, Jul 31, 2012 at 4:08 AM, Dave Cottlehuber <da...@muse.net.nz> wrote:
> On 30 July 2012 18:41, Simon Metson <si...@cloudant.com> wrote:
>> Hi,
>> Has this moved on at all? Thinking about it a bit more (off and on)
>> I'm inclined to suggest that DocBook isn't the greatest format. If
>> we stored the docs in markdown it would be easier for people to
>> edit/contribute (they could view the docs and make changes in
>> github without having to compile/install anything). I'm happy to
>> put some cycles into converting whats there to a bunch of
>> markdown. Rendering that in futon is pretty easy too.
>>
>> I can see the benefits of DocBook for writing a book, but I'm not
>> sure that its what's needed here - it seems like using a hammer to
>> crack a nut.
>> Cheers
>> Simon
>
> +1. TL;DR:
>
> Let's focus on the *real* issue: despite having a great working base
> for over 5 months now, the docs contribution barrier is too high for
> even the dev community to make any progress.
>
> I now have a working export of DocBook -> Markdown, using Pandoc[1],
> which can be turned into HTML5, PDFs or ePUBs easily.
>
> Notes/results: https://gist.github.com/3212532#file_readme.md
> If you want epub or PDF, try using this branch:
> https://github.com/dch/couchdb/tree/docs
>
> My next steps:
>
> - check the details (in daytime)
> - document how to add a chapter/section
> - make a list of things to be added to reach 1.2.0 equivalence
> - get stuck in & get helpers
> - sort out CSS & images for futon & standalone viewing
> - integrate build step with autotools
> - get this into 1.3.0
>
> Long Version:
>
> Tonight, I tried to add a simple section to the XML pages, explaining the new
> [vendor] field in default.ini. I gave up after an hour of faffing about.
>
> If I'm not able to drive it, we set the contribution barrier too high methinks.
>
> I then tried installing XML editors and trying to make sense
> of the admittedly awesome couchbase doc structure, and related
> tools. I still failed, I was unable to add a simple chapter, or clarify
> the new [vendor] section in default.ini.
>
> Clearly somebody who *knows* DocBook and XML will be annoyed
> at my incompetence, but so far none of those people have the time
> to move our docs along, and more importantly, nor do most of our
> contributors. I want this in 1.3.0, as a solid baseline for the next
> release with bigcouch included.
>
> The output is not yet perfect, but I believe its workable:
>
> - the structure is right (chapters, headings, links, code)
> - integrating small sections works (merge chapters -> larger doc)
> - images are missing (I was too lazy to copy them in)
> - some tables are not right yet (ditto)
> - I don't have CSS right (ditto)
>
> Let's do the conversion, get the docs into master, and get them
> updated for 1.3. I'm up for it & I'm not waiting for DocBook nirvana
> to arrive, because the current barrier to contribution is simply too high.
>
> Pandoc[1], is a GPL-licensed Haskell library. It's available as a binary
> on pretty much every system we dev on, either in package manager tools
> or via download. And it just works, surprisingly well too, and it's
> fricking FAST. Blazing. DocBook -> HTML5 in seconds, without
> installing FOP, 6 jars, 12 perl modules, and the kitchen sink.
>
> Let's get this off the ground. Please.
>
> A+
> Dave
>
> [1]: http://johnmacfarlane.net/pandoc/
Re: Docs, second try
Posted by Dave Cottlehuber <da...@muse.net.nz>.
On 30 July 2012 18:41, Simon Metson <si...@cloudant.com> wrote:
> Hi,
> Has this moved on at all? Thinking about it a bit more (off and on)
> I'm inclined to suggest that DocBook isn't the greatest format. If
> we stored the docs in markdown it would be easier for people to
> edit/contribute (they could view the docs and make changes in
> github without having to compile/install anything). I'm happy to
> put some cycles into converting whats there to a bunch of
> markdown. Rendering that in futon is pretty easy too.
>
> I can see the benefits of DocBook for writing a book, but I'm not
> sure that its what's needed here - it seems like using a hammer to
> crack a nut.
> Cheers
> Simon
+1. TL;DR:
Let's focus on the *real* issue: despite having a great working base
for over 5 months now, the docs contribution barrier is too high for
even the dev community to make any progress.
I now have a working export of DocBook -> Markdown, using Pandoc[1],
which can be turned into HTML5, PDFs or ePUBs easily.
Notes/results: https://gist.github.com/3212532#file_readme.md
If you want epub or PDF, try using this branch:
https://github.com/dch/couchdb/tree/docs
My next steps:
- check the details (in daytime)
- document how to add a chapter/section
- make a list of things to be added to reach 1.2.0 equivalence
- get stuck in & get helpers
- sort out CSS & images for futon & standalone viewing
- integrate build step with autotools
- get this into 1.3.0
Long Version:
Tonight, I tried to add a simple section to the XML pages, explaining the new
[vendor] field in default.ini. I gave up after an hour of faffing about.
If I'm not able to drive it, we set the contribution barrier too high methinks.
I then tried installing XML editors and trying to make sense
of the admittedly awesome couchbase doc structure, and related
tools. I still failed, I was unable to add a simple chapter, or clarify
the new [vendor] section in default.ini.
Clearly somebody who *knows* DocBook and XML will be annoyed
at my incompetence, but so far none of those people have the time
to move our docs along, and more importantly, nor do most of our
contributors. I want this in 1.3.0, as a solid baseline for the next
release with bigcouch included.
The output is not yet perfect, but I believe its workable:
- the structure is right (chapters, headings, links, code)
- integrating small sections works (merge chapters -> larger doc)
- images are missing (I was too lazy to copy them in)
- some tables are not right yet (ditto)
- I don't have CSS right (ditto)
Let's do the conversion, get the docs into master, and get them
updated for 1.3. I'm up for it & I'm not waiting for DocBook nirvana
to arrive, because the current barrier to contribution is simply too high.
Pandoc[1], is a GPL-licensed Haskell library. It's available as a binary
on pretty much every system we dev on, either in package manager tools
or via download. And it just works, surprisingly well too, and it's
fricking FAST. Blazing. DocBook -> HTML5 in seconds, without
installing FOP, 6 jars, 12 perl modules, and the kitchen sink.
Let's get this off the ground. Please.
A+
Dave
[1]: http://johnmacfarlane.net/pandoc/
Re: Docs, second try
Posted by Simon Metson <si...@cloudant.com>.
Hi,
Has this moved on at all? Thinking about it a bit more (off and on) I'm inclined to suggest that DocBook isn't the greatest format. If we stored the docs in markdown it would be easier for people to edit/contribute (they could view the docs and make changes in github without having to compile/install anything). I'm happy to put some cycles into converting whats there to a bunch of markdown. Rendering that in futon is pretty easy too.
I can see the benefits of DocBook for writing a book, but I'm not sure that its what's needed here - it seems like using a hammer to crack a nut.
Cheers
Simon
On Thursday, 21 June 2012 at 21:25, Noah Slater wrote:
> I am publicly taking ownership of this project, and will run point on it.
>
> I've not contributed code to CouchDB for a while, and my free personal time is scarce, but I am in the best position to do this work. I know Autotools and DocBook very well, and have integrated them in the past.
>
Re: Docs, second try
Posted by Noah Slater <ns...@tumbolia.org>.
I am publicly taking ownership of this project, and will run point on it.
I've not contributed code to CouchDB for a while, and my free personal time is scarce, but I am in the best position to do this work. I know Autotools and DocBook very well, and have integrated them in the past.
On 21 Jun 2012, at 16:25, Simon Metson <si...@cloudant.com> wrote:
> Hi,
>> This has nothing to do with docbook, we generate HTML and we can link to that in Futon, I don't think we want to generate the Futon-docs part in docbook, but happy to be proven wrong. I think it'd be easer to make a docs.html in futon that keeps the header and sidebar and just shows the /_docs/... link.
> I'm probably just showing how little I know about docbook ;) (not helped by their documentation wiki being down currently…). If this was sphinx I'd write a theme that would be applied to all the generated html, making it easy to plug into futon (or style for other purposes). I'm assuming we could do the same thing with docbook, though putting the generated content in an iframe is probably quicker (and is what I've just done).
>>
>>> What about things like pulling in Dale's jquery.couch.js docs (daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)? (http://daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?)
>>
>>
>> We should definitely consider this, but I think that is out of scope for this particular patch.
> Agreed, just thinking ahead a bit.
> Cheers
> Simon
Re: Docs, second try
Posted by Simon Metson <si...@cloudant.com>.
Hi,
> This has nothing to do with docbook, we generate HTML and we can link to that in Futon, I don't think we want to generate the Futon-docs part in docbook, but happy to be proven wrong. I think it'd be easer to make a docs.html in futon that keeps the header and sidebar and just shows the /_docs/... link.
I'm probably just showing how little I know about docbook ;) (not helped by their documentation wiki being down currently…). If this was sphinx I'd write a theme that would be applied to all the generated html, making it easy to plug into futon (or style for other purposes). I'm assuming we could do the same thing with docbook, though putting the generated content in an iframe is probably quicker (and is what I've just done).
>
> > What about things like pulling in Dale's jquery.couch.js docs (daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)? (http://daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?)
>
>
> We should definitely consider this, but I think that is out of scope for this particular patch.
Agreed, just thinking ahead a bit.
Cheers
Simon
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
On Jun 21, 2012, at 17:01 , Jan Lehnardt wrote:
>
> On Jun 21, 2012, at 16:55 , Simon Metson wrote:
>
>> Hey,
>>> Sorry, my bad, it actually ships with Macs as far as I can tell. I updated the README.
>>>
>>>
>>
>> Cool.
>>> Did you mean to do `make dev && utils/run` or is `./bin/couchdb` done in a `make install` target?
>> It was done in the make install target. make dev && utils/run works.
>>>
>>>> * 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 can't reproduce this in my dev repo or clean checkout.
>> Ah, I cocked up; I'd accidentally removed the jars when running the make clean :)
>>> It is already linked up in Futon, pointing to /_docs/manual/couchdb-manual.html-dir/index.html (see 06210b9), but it just jumps to the docs and out of futon, which isn't very user-friendly. We could iframe things, or open the docs in a new window/tab, although I tend to not like that :)
>>>
>
> Cool, thanks :)
>
>>>
>>>
>>
>> I think I mean where do we go now. Agree that integrating the docs into futon would be nice (though I don't know how to do that with docbook, not used it before now, will dig in).
>
> This has nothing to do with docbook, we generate HTML and we can link to that in Futon, I don't think we want to generate the Futon-docs part in docbook, but happy to be proven wrong. I think it'd be easer to make a docs.html in futon that keeps the header and sidebar and just shows the /_docs/... link.
Like this:
https://dl.dropbox.com/u/82149/couchdb-futon-docs.png
Source:
https://github.com/janl/couchdb/commit/bcfa57bee491837e91c65045870aaddf706b303d
Plus fine-tuning :)
Cheers
Jan
--
>
>
>> What about things like pulling in Dale's jquery.couch.js docs (daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?
>
> We should definitely consider this, but I think that is out of scope for this particular patch.
>
>
>> Once this is integrated with the main make I guess it makes sense to have a "normal" make just create the html for serving, and making building the pdf etc something you explicitly trigger.
>
> Agreed :)
>
> Cheers
> Jan
> --
>
>
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
On Jun 21, 2012, at 16:55 , Simon Metson wrote:
> Hey,
>> Sorry, my bad, it actually ships with Macs as far as I can tell. I updated the README.
>>
>>
>
> Cool.
>> Did you mean to do `make dev && utils/run` or is `./bin/couchdb` done in a `make install` target?
> It was done in the make install target. make dev && utils/run works.
>>
>>> * 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 can't reproduce this in my dev repo or clean checkout.
> Ah, I cocked up; I'd accidentally removed the jars when running the make clean :)
>> It is already linked up in Futon, pointing to /_docs/manual/couchdb-manual.html-dir/index.html (see 06210b9), but it just jumps to the docs and out of futon, which isn't very user-friendly. We could iframe things, or open the docs in a new window/tab, although I tend to not like that :)
>>
Cool, thanks :)
>>
>>
>
> I think I mean where do we go now. Agree that integrating the docs into futon would be nice (though I don't know how to do that with docbook, not used it before now, will dig in).
This has nothing to do with docbook, we generate HTML and we can link to that in Futon, I don't think we want to generate the Futon-docs part in docbook, but happy to be proven wrong. I think it'd be easer to make a docs.html in futon that keeps the header and sidebar and just shows the /_docs/... link.
> What about things like pulling in Dale's jquery.couch.js docs (daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?
We should definitely consider this, but I think that is out of scope for this particular patch.
> Once this is integrated with the main make I guess it makes sense to have a "normal" make just create the html for serving, and making building the pdf etc something you explicitly trigger.
Agreed :)
Cheers
Jan
--
Re: Docs, second try
Posted by Simon Metson <si...@cloudant.com>.
Hey,
> Sorry, my bad, it actually ships with Macs as far as I can tell. I updated the README.
>
>
Cool.
> Did you mean to do `make dev && utils/run` or is `./bin/couchdb` done in a `make install` target?
It was done in the make install target. make dev && utils/run works.
>
> > * 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 can't reproduce this in my dev repo or clean checkout.
Ah, I cocked up; I'd accidentally removed the jars when running the make clean :)
> It is already linked up in Futon, pointing to /_docs/manual/couchdb-manual.html-dir/index.html (see 06210b9), but it just jumps to the docs and out of futon, which isn't very user-friendly. We could iframe things, or open the docs in a new window/tab, although I tend to not like that :)
>
>
>
I think I mean where do we go now. Agree that integrating the docs into futon would be nice (though I don't know how to do that with docbook, not used it before now, will dig in). What about things like pulling in Dale's jquery.couch.js docs (daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?
Once this is integrated with the main make I guess it makes sense to have a "normal" make just create the html for serving, and making building the pdf etc something you explicitly trigger.
Cheers
Simon
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
Hi Simon,
thanks for the feedback!
On Jun 21, 2012, at 14:27 , Simon Metson 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
Sorry, my bad, it actually ships with Macs as far as I can tell. I updated the README.
> * 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 you mean to do `make dev && utils/run` or is `./bin/couchdb` done in a `make install` target?
> * 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 can't reproduce this in my dev repo or clean checkout.
> 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...
It is already linked up in Futon, pointing to /_docs/manual/couchdb-manual.html-dir/index.html (see 06210b9), but it just jumps to the docs and out of futon, which isn't very user-friendly. We could iframe things, or open the docs in a new window/tab, although I tend to not like that :)
Cheers
Jan
--
>
>
> 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
>>> --
>>>
>>
>>
>>
>
>
Re: Docs, second try
Posted by Simon Metson <si...@cloudant.com>.
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
> > --
> >
>
>
>
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
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` 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`.
>
> Any help is appreciated!
> Cheers
> Jan
> --
>
>
>
>
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
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
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` 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`.
Any help is appreciated!
Cheers
Jan
--
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
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.
Cheers
Jan
--
>
> There's plenty of room for improvement:
>
> - better integration into Futon
> - more approachable ToC (expandable sub-levels, e.g.)
> - better styling
> - more docs :)
>
> Let us know if you want to help out with this!
>
> Cheers
> Jan
> --
>
> * Noah, could you have a look at my license.skip commit and tell me
> I'm not doing anything fishy?
>
> https://github.com/janl/couchdb/commit/56b664854209e00d0ff549352970abd269adb24b
>
> ** The last commit I had to rebase to keep the history nice, that means
> the branch had to be pushed with -f. This is only relevant if you have
> checked out the branch in the past and made edits to it.
>
> On Jun 11, 2012, at 22:05 , Jan Lehnardt wrote:
>
>> Hey all,
>>
>> remember that big commit I made to a new docs branch with all
>> the .jar files in it and whatnot? Well, I've cleaned it up and
>> pushed it to GitHub:
>>
>> https://github.com/janl/couchdb/tree/docs
>>
>> The README states all prerequisites.
>>
>> I have ripped all the .jar files out of the repo and put them
>> in a .tgz up on:
>>
>> http://people.apache.org/~jan/couchdb/couchdb-doc-jars.tgz
>>
>> To build the docs go to share/docs and run
>>
>> $ COUCHDB_DOC_JAR_DIR=/path/to/doc/jars make docs
>>
>> This is the easiest I could think of for pushing this forward.
>>
>> I also went through all the other resources in the share/docs
>> directory and double checked the licensing on all items and
>> couldn't find anything incompatible. I've still to update
>> the NOTICE file to make this land on ASF infrastructure, but
>> I think we are in a good position.
>>
>> Please check out the branch and give us any feedback, I'd like
>> to finally finally get this merged soon :)
>>
>> Cheers
>> Jan
>> --
>>
>
Re: Docs, second try
Posted by Jan Lehnardt <ja...@apache.org>.
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.
There's plenty of room for improvement:
- better integration into Futon
- more approachable ToC (expandable sub-levels, e.g.)
- better styling
- more docs :)
Let us know if you want to help out with this!
Cheers
Jan
--
* Noah, could you have a look at my license.skip commit and tell me
I'm not doing anything fishy?
https://github.com/janl/couchdb/commit/56b664854209e00d0ff549352970abd269adb24b
** The last commit I had to rebase to keep the history nice, that means
the branch had to be pushed with -f. This is only relevant if you have
checked out the branch in the past and made edits to it.
On Jun 11, 2012, at 22:05 , Jan Lehnardt wrote:
> Hey all,
>
> remember that big commit I made to a new docs branch with all
> the .jar files in it and whatnot? Well, I've cleaned it up and
> pushed it to GitHub:
>
> https://github.com/janl/couchdb/tree/docs
>
> The README states all prerequisites.
>
> I have ripped all the .jar files out of the repo and put them
> in a .tgz up on:
>
> http://people.apache.org/~jan/couchdb/couchdb-doc-jars.tgz
>
> To build the docs go to share/docs and run
>
> $ COUCHDB_DOC_JAR_DIR=/path/to/doc/jars make docs
>
> This is the easiest I could think of for pushing this forward.
>
> I also went through all the other resources in the share/docs
> directory and double checked the licensing on all items and
> couldn't find anything incompatible. I've still to update
> the NOTICE file to make this land on ASF infrastructure, but
> I think we are in a good position.
>
> Please check out the branch and give us any feedback, I'd like
> to finally finally get this merged soon :)
>
> Cheers
> Jan
> --
>