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.
>
>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:
After some more digging around I found that NOT having the different parts in the same documentation tree seems suboptimal, since having all files in the same tree makes it very easy to cross reference and link between the parts. I imagine that we want to link heavily between the User Manual and Demos (Perhaps also the Tutorial).
Sphinx makes it very easy to build separate PDFs for for the individual parts like C++ Tutorial, Python Tutorial, C++ Demos etc. so that shouldn't be a problem.
