On Tue, Apr 20, 2010 at 10:16:27AM +0200, Kristian Oelgaard wrote: > > > On 19 April 2010 21:43, Anders Logg <[email protected]> wrote: > >On Mon, Apr 19, 2010 at 10:53:58AM +0200, Kristian Oelgaard wrote: > >> > >> > >>On 17 April 2010 20:04, Anders Logg <[email protected]> wrote: > >>>On Fri, Apr 16, 2010 at 05:15:52PM +0200, [email protected] 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 > > If we use Python as a model, Installation, Contributing, Guidelines should be > moved one level up. > See http://docs.python.org/index.html. > I'm creating a separate page that can work as an overview of the > documentation we have a available. It will contain external links to > Tutorial, User manual, Demos and thus work in much the same way as the Python > index page. Let's see how it looks and works.
ok, sounds good. -- Anders > > Demos (a third document) > > Overview > > Linear algebra > > Name of demo > > Name of demo > > ... > > Meshes > > Name of demo > > ... > > Agree. > > Kristian > >
signature.asc
Description: Digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
