fenics team mailing list archive

[Kristian Oelgaard <k.b.oelgaard@xxxxxxxxx>]

On 17 April 2010 20:04, Anders Logg <logg@xxxxxxxxx> wrote:
> 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.

Sounds reasonable, from the files it looks like it's just a matter of supplying the template somehow.

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

I agree that the Tutorial and User Manual should probably have their separate build directory.
Then the PDF versions of the Tutorial and User Manual will also be separated in a simple way.
(Personally, I don't see why anyone will ever use the PDF version of the User Manual if the HTML version is available.)

However, w.r.t. the introduction, installation, contributing and guidelines (I agree that appendices should be in the User Manual) I was trying to put things in a larger perspective such that the FEniCS Documentation (the main page) explains the three ways that we offer help to our users:

1. Tutorial (a quick overview)
2. User Manual (which I think will be more of a DOLFIN programmer's reference)
3. Demos (code that users can copy and modify to get started)

I guess these 3 parts should be in separate directories and then linked to from the main page.

The installation section should then cover the minimal installation of FEniCS projects which is needed to run all code presented in the documentation.

Since all FEniCS projects are managed in the same way on Launchpad, I thought it was a good idea to have a general page on how to contribute to FEniCS. That will allow us to make the procedure for merging, patching etc. more uniform across projects.

My intention with the guidelines page is to have a list of specifications that should be followed to ensure a uniform documentation, it is thus only concerned with the documentation pages.

>  introductioin

Yes, each part (Tutorial, User Manual, Demos) should have an introduction that explains the purpose of what follows.

>  installation

I was hoping to handle this on the 'global level' as explained above.

>  linear algebra
>  meshes
>  ...
>  contributing

Again, I was hoping to handle this on the 'global level' as explained above.

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

Or rename User Manual to Programmer's Reference?

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

Sure.

Kristian

> --
> Anders
>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkvJ+DQACgkQTuwUCDsYZdHHIwCfUNTqgjhT/WpexaDdIRlVvuKR
> nIkAnROeJ62tDTQH4h3JDBJ+JcEmTm6T
> =eb8R
> -----END PGP SIGNATURE-----

Attachment: signature.asc
Description: OpenPGP digital signature