[IPython-dev] Website

Fernando Perez fperez.net at gmail.com
Wed Jun 1 16:32:58 EDT 2011

Hi Thomas,

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

make upload

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
problem already:


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