doc: stdlib => sphinx, manual => website

170 views
Skip to first unread message

Stefan Karpinski

unread,
May 23, 2012, 6:14:27 PM5/23/12
to Julia Dev
I really like sphinx for the stdlib documentation, and it helps to have the documentation in the same repo as the code. However, I still really prefer to read the manual on the Julia website, so I propose that we keep it there. Thoughts?

Patrick O'Leary

unread,
May 23, 2012, 6:19:08 PM5/23/12
to juli...@googlegroups.com
Reasonable; they should link to one another, of course.

Mike Nolta

unread,
May 23, 2012, 6:45:16 PM5/23/12
to juli...@googlegroups.com
Is this just an aesthetic problem? If so, we can write our own sphinx theme.

-Mike

Stefan Karpinski

unread,
May 23, 2012, 6:49:56 PM5/23/12
to juli...@googlegroups.com
That's entirely possible. The current version is pretty busy.

Stefan Karpinski

unread,
May 23, 2012, 11:22:47 PM5/23/12
to juli...@googlegroups.com
I am also concerned about how to keep the online manual in sync. Can we easily publish the generated html to the website (which is rendered using jekyll). One of the things I like about the current version is that we only check in the source and github beautifully takes care to the generation parts. (Now that I fixed the DNS setup, it's been rock solid and completely reliable.) Mike, what are your thoughts on that?

Mike Nolta

unread,
May 24, 2012, 4:04:32 PM5/24/12
to juli...@googlegroups.com
On Wed, May 23, 2012 at 11:22 PM, Stefan Karpinski <ste...@karpinski.org> wrote:
> I am also concerned about how to keep the online manual in sync. Can we
> easily publish the generated html to the website (which is rendered using
> jekyll). One of the things I like about the current version is that we only
> check in the source and github beautifully takes care to the generation
> parts. (Now that I fixed the DNS setup, it's been rock solid and completely
> reliable.) Mike, what are your thoughts on that?
>

If we host on readthedocs.org, they have a github commit hook for
auto-rebuilding:

http://read-the-docs.readthedocs.org/en/latest/webhooks.html

I wrote a simple sphinx theme which mimics the design of
julialang.org, and you can check it out here:

http://julia-test.readthedocs.org

-Mike

Stefan Karpinski

unread,
May 24, 2012, 4:13:24 PM5/24/12
to juli...@googlegroups.com
Oh, very nice. Maybe we can keep the main site hosted at GitHub (which handles load on, say, blog posts very well (now that I fixed the DNS setup)) and just make julialang.org/manual/ redirect to manual.julialang.org which can be hosted at readthedocs.org. I really don't want to break any existing links, however. We may need to setup a bunch of static redirects where all the manual pages are currently. A little ugly, but not the end of the world, and definitely doable.

Mike Nolta

unread,
May 24, 2012, 4:56:47 PM5/24/12
to juli...@googlegroups.com
On Thu, May 24, 2012 at 4:13 PM, Stefan Karpinski <ste...@karpinski.org> wrote:
> Oh, very nice. Maybe we can keep the main site hosted at GitHub (which
> handles load on, say, blog posts very well (now that I fixed the DNS setup))
> and just make julialang.org/manual/ redirect to manual.julialang.org which
> can be hosted at readthedocs.org. I really don't want to break any existing
> links, however. We may need to setup a bunch of static redirects where all
> the manual pages are currently. A little ugly, but not the end of the world,
> and definitely doable.
>

Sounds good to me. I've deleted julia-test, which should clear the way
for you to set up the official RTD account.

-Mike

Stefan Karpinski

unread,
May 24, 2012, 4:57:55 PM5/24/12
to juli...@googlegroups.com
Ok, will do.

Stefan Karpinski

unread,
May 24, 2012, 5:05:41 PM5/24/12
to juli...@googlegroups.com

Jeff Bezanson

unread,
May 26, 2012, 2:24:56 AM5/26/12
to juli...@googlegroups.com
So should all manual edits now go to julia/doc/manual?

Mike Nolta

unread,
May 29, 2012, 2:31:15 PM5/29/12
to juli...@googlegroups.com
On Thu, May 24, 2012 at 5:05 PM, Stefan Karpinski <ste...@karpinski.org> wrote:
> Ok, done: http://readthedocs.org/docs/julia/en/latest/manual/
>

Has the commit hook been, er, hooked up yet? The docs don't seem to be updating.

Stefan Karpinski

unread,
May 29, 2012, 3:52:24 PM5/29/12
to juli...@googlegroups.com
Oops. Yeah, I didn't do that part. Will do it.

Stefan Karpinski

unread,
May 29, 2012, 3:56:21 PM5/29/12
to juli...@googlegroups.com
Ok, I tried to set this up but the commit hook may be broken. I was expecting to have to put a URL up there for the commit hook to post to, but the form for the hook didn't have anything in it.

Mike Nolta

unread,
May 31, 2012, 6:55:17 PM5/31/12
to juli...@googlegroups.com
On Tue, May 29, 2012 at 3:56 PM, Stefan Karpinski <ste...@karpinski.org> wrote:
> Ok, I tried to set this up but the commit hook may be broken. I was
> expecting to have to put a URL up there for the commit hook to post to, but
> the form for the hook didn't have anything in it.
>

I guess github & rtfd figure this out automagically. But the
ReadTheDocs service hook is active, right? Just double-checking,
because the docs still aren't auto-updating, and i'm about to file an
issue.

-Mike

Stefan Karpinski

unread,
May 31, 2012, 7:17:15 PM5/31/12
to juli...@googlegroups.com
I tried to activate it but the little button next to it just shows up red. So I guess that means it's broken. File away...
Reply all
Reply to author
Forward
0 new messages