On Mon, Apr 19, 2010 at 10:53:58AM +0200, Kristian Oelgaard wrote:
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.)
Me neither but it might be good to have the possibility of printing
the manual if needed.
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.
Perhaps Python is a good model to follow, see
http://www.python.org/doc/. It's kind of similar to what you have
now, but what you have named User Manual is called Library Reference /
Language Reference. They have Tutorial as one item in the table of
contents but there are advantages to having it in a separate document
(so it can be printed).
How about this:
Tutorial (one document)
User manual (a second document)
Introduction
Installation
Library reference (documenting the API)
Contributing
Guidelines
Appendices
