You can get running very quickly given sphinx's "sphinx-quickstart"
command. In ZK case I found a script that converted our forrest docs
(simpledocbook format) into reST with ~95% accuracy. Given Avro has
limited forrest based docs this should be fairly quick to do, regardless
if a script is avail or not.
http://sphinx.pocoo.org/intro.html
The rub is that you get the default theme/site out of the box. Something
like this look: http://docs.python.org/
Then you need to start changing the templates themselves. Here's an
example of some styling changes:
http://www.sqlalchemy.org/docs/
Another example - the sphinx site & docs are all created using sphinx:
http://sphinx.pocoo.org/index.html
I'd be happy to create a patch that demonstrates the basic structure,
something we could play with to see if ppl like Sphinx or not, and also
experiment with the options. I'm not a site designer though.
Patrick
On 06/01/2010 09:03 AM, Bruce Mitchener wrote:
I think what would help a lot is for someone to:
* Come up with a plan of attack.
* Start doing the work.
My understanding is that we have a couple of things to convert to Sphinx:
* Python docs
* Avro specification (currently forrest)
* Avro website (currently forrest)
It is also my understanding from Patrick Hunt that the site would the
most difficult and the other things should be relatively easy.
Any chance that we have some volunteers, even if only for one of the
pieces rather than all of it?
- Bruce
On Tue, Jun 1, 2010 at 10:55 PM, Chad Harrington
<[email protected] <mailto:[email protected]>> wrote:
We use Sphinx at work. The ReST syntax is a bit clunky in my
opinion, but it makes very nice looking PDFs and searchable HTML
docs from a single source. We are quite happy with it.
Chad Harrington
[email protected] <mailto:[email protected]>
On Tue, Jun 1, 2010 at 8:07 AM, Jeff Hammerbacher
<[email protected] <mailto:[email protected]>> wrote:
Note that this issue has been filed at
https://issues.apache.org/jira/browse/AVRO-319.
On Mon, May 31, 2010 at 11:56 PM, Jeff Hodges
<[email protected] <mailto:[email protected]>> wrote:
I am literally downloading a 1.5 jdk from some random
cs.washington.edu <http://cs.washington.edu> URL because no
one else on the web seems to have
java 1.5 built for OS X 10.6.
I'm hearing from the Forrest PMC (Grant McDonald) that the
release
after this coming release will have 1.6 support. However,
that first
release (not the second one with 1.6 support!) is going to
happen in
"the next couple of months". This is, of course, after 3
years of no
releases.
I think it makes sense for us to move to Sphinx or similar.
--
Jeff
On Mon, May 31, 2010 at 11:39 PM, Scott Carey
<[email protected] <mailto:[email protected]>>
wrote:
> Don't make the mistake that I did and think you can
simply change the symlink to point to the directory with
Java 1.5 -- it actually has to be placed where the symlink is.
>
> For posterity-- The below is from my email on the topic
from April 12, 2010:
>
> ----
> OS-X Snow Leopard tips:
> For those in a similar situation, the work-around posted
in AVRO-318 makes Java 5 the default for most apps and
overrides Java 6. But turning off Java 6 is not necessary.
> Getting a copy of Java 1.5 and placing it in
/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0
and setting up the links is sufficient. You do not have to
make Java 1.5 the default and can continue to use Java 1.6
for everything but Forrest. I used the first few steps
here:
http://wiki.oneswarm.org/index.php/OS_X_10.6_Snow_Leopard
but stopped after recreating the symbolic links.
> Additionally, the build.xml will not run without passing
in
-Djava5.home=/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
-Dforrest.home=<location of Forrest>.
> ----
>
> On May 31, 2010, at 11:31 PM, Jeff Hodges wrote:
>
>> Sigh, I didn't notice the symlink before. That's what's
happening. Thanks.
>> --
>> Jeff
>>
>> On Mon, May 31, 2010 at 11:17 PM, Scott Carey
<[email protected] <mailto:[email protected]>>
wrote:
>>> Are you on Snow Leopard? If so, you manually have to
install a copy of Java 5 and overwrite the Mac symlinks in
just the right way. You don't have to change the default
system JVM to 1.5 though.
>>>
>>> Does the symlink
/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0
point to a 1.6 JVM? That is what it does on Snow Leopard by
default. forrest is somehow not forward compatible with Java
1.6. The trick to getting it to work is to both set the
property to that symlink, and make sure that symlink points
to an actual java 1.5 install.
>>>
>>> There are a few threads from the Avro dev list over the
past ~7 months that discuss the steps needed to get it to
work in more detail.
>>>
>>> -Scott
>>>
>>> On May 31, 2010, at 10:49 PM, Jeff Hodges wrote:
>>>
>>>> Hey,
>>>> I'm running into issues build the docs. Specifically,
in avro trunk,
>>>> I'm running:
>>>>
>>>> ant
-Djava5.home=/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
>>>>
-Dforrest.home=/Users/jhodges/projects/apache-forrest-0.8/ doc
>>>>
>>>> on OS X. Hoever, I'm getting this gross error for
which all the google
>>>> results say "RTFM n00b. Use Java5."
>>>>
>>>> [exec] validate-sitemap:
>>>> [exec]
/Users/jhodges/projects/apache-forrest-0.8/main/webapp/resources/schema/relaxng/sitemap-v06.rng:72:31:
>>>> error: datatype library
"http://www.w3.org/2001/XMLSchema-datatypes";
>>>> not recognized
>>>>
>>>> But I've included -Djava5.home right there. What am I
missing?
>>>> --
>>>> Jeff
>>>
>>>
>
>
