fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Fri, Apr 16, 2010 at 05:15:52PM +0200, k.b.oelgaard@xxxxxxxxx wrote:
>
> Hello,
>
> I've started setting up the files for the FEniCS documentation.
> Try:
>
> bzr branch lp:fenics-doc
> cd fenics-doc
> make html
> your-favorite-web-browser build/html/index.html
>
> to see the result. Everything is up for discussion and comments/suggestions are welcome.
>
> I also added some more detailed blueprints at:
>
> https://blueprints.launchpad.net/fenics-doc
>
> have a look and feel free to join the discussion or sign up for a blueprint.
>
> One question though, where do we publish the HTML/PDF files that are generated?
> I guess we should put them where
>
> http://new.fenics.org/Main_Page
>
> is located and then link to the index.html page?
>
> Kristian

It looks like a good start. Here are some initial comments:

1. The default Sphinx theme looks really good. But I suspect we will
want to theme it to match the new redesigned web pages (in progress).
Harish can comment on this.

2. I'm not sure where to put things on the server. There are two
possible locations in the new content tree Harish has sketched out:

  User - Using
  Developer - Documentation

What you are writing is a little bit of both. Perhaps it should be
split up. Opinions?

For now, we can just put it somewhere for people to look at what's
going on, like www.fenics.org/newdoc.

Johannes, could you set up a cronjob on the server to pull the manual,
generate it and copy the files to that location?

3. It looks suboptimal to have Tutorial and User Manual as part of the
documentation tree. I think Tutorial and User Manual should be two
different documents (linked from some other HTML page). And most of
what you have in the top list right now (introduction, installation,
contributing, guidelines, appendices) should then be part of the user
manual. The table of contents of the user manual could be similar to
what we have now in the old DOLFIN user manual:

  introductioin
  installation
  linear algebra
  meshes
  ...
  contributing
  ...

Or is it better to have a third document: programmer's reference?

4. Let's keep the discussion regarding the documentation open here on
this list.

--
Anders

Attachment: signature.asc
Description: Digital signature