couchdb-dev mailing list archives

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

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


Mime
View raw message