fperez.net at gmail.com
Wed Jun 1 16:32:58 EDT 2011
On Wed, Jun 1, 2011 at 2:26 AM, Thomas Kluyver <takowl at gmail.com> wrote:
> This makes sense. I understand we can easily create a CNAME if we're hosting
> the site using Github pages.
>> * Using sphinx for the entire site as matplotlib does.
> This I'm less sure about. Sphinx is great for documentation, but I don't
> think it works so well for a whole website:
> * The layout is really geared towards writing documentation.
> * With so many projects now using Sphinx for docs, people instantly
> recognise the layout and think 'docs'. Whenever I go to matplotlib's
> website, I have this feeling that I've missed the homepage somewhere and
> skipped straight to the docs.
> * We'll want to update parts of the website fairly often. If every small
> change requires the site to be checked out as source, rebuilt by Sphinx
> (with all its dependencies) and reuploaded, the site's just going to get out
> of date.
Mmh, I actually think that sphinx is a good choice, given your points
above. Hear me out:
- layout: that's just a matter of theming, and a small amount of
theme/template work (that would need to be done anyway for any site)
can make a sphinx-based site look completely different.
- updates: I update my site (sphinx-based: http://fperez.org) with a simple
that runs 'make html' and then rsyncs the content up. I actually find
that to be the easiest way to do it, since it reuses the tools I
already use for everything else (make, git, sphinx, rsync).
I *really* want the website content to be under version control, and
also to be written in reST instead of hand-coded html (except possibly
for a few visually key pages like the main page, if necessary). If
it's in simple reST we're much more likely to actually keep it updated
than if we have to hand-edit html, which I find fairly unpleasant.
One of the things that I sadly let fall through the cracks when I came
back from India, was that Komal (CC'd here), one of the students who
participated in the IPython sprints, did make headway into this
She took my advice of porting our existing content to sphinx and got
things going, and unfortunately upon my return I never followed up on
this (my apology, BTW). I haven't had a chance to review it yet, but
that was done based on the plan of building with sphinx from our
existing content on the moin wiki.
>> * Moving the wiki stuff over to github.
> Again, this makes sense. I take it we're talking about turning on the wiki
> feature in Github, rather than just moving the content into github pages?
I think the main site shouldn't *be* a wiki, but that we should *have*
a wiki. A wiki is good for certain things, and having one will be
good. The github one may be OK, I haven't actually used it. Other
things equal, github will win on the grounds of good tool reuse.
> I think the key thing is to work out how we want to divide content between:
> - Documentation
> - A wiki
> - A landing page (or a small collection of pages)
I think the landing page should be visually very good (and I'm awful
at that), and then we should have a few pages for specific areas of
content that don't need to be in the manuals themselves. But I
suspect with a bit of sphinx theming, all those could be done nicely
in reST, leaving the wiki for community-edited material and the manual
for full-on docs.
More information about the IPython-dev