fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Thu, Aug 26, 2010 at 03:34:43PM +0200, Kristian Ølgaard wrote:
> On 26 August 2010 15:23, Anders Logg <logg@xxxxxxxxx> wrote:
> > On Thu, Aug 26, 2010 at 03:21:33PM +0200, Anders Logg wrote:
> >> On Thu, Aug 26, 2010 at 03:18:14PM +0200, Kristian Ølgaard wrote:
> >> > On 26 August 2010 15:03,  <noreply@xxxxxxxxxxxxx> wrote:
> >> > > ------------------------------------------------------------
> >> > > revno: 67
> >> > > committer: Anders Logg <logg@xxxxxxxxx>
> >> > > branch nick: fenics-doc
> >> > > timestamp: Thu 2010-08-26 14:41:15 +0200
> >> > > message:
> >> > >  Trying to add a link that doesn't work. What am I missing here?
> >> > > modified:
> >> > >  source/programmers-reference/cpp/index.rst
> >> > >  source/styleguides.rst
> >> > >
> >> > >
> >> > >
> >> > > You are subscribed to branch lp:fenics-doc.
> >> > > To unsubscribe from this branch go to https://code.launchpad.net/~fenics-core/fenics-doc/main/+edit-subscription
> >> > >
> >> > > === modified file 'source/programmers-reference/cpp/index.rst'
> >> > > --- source/programmers-reference/cpp/index.rst  2010-08-26 10:29:13 +0000
> >> > > +++ source/programmers-reference/cpp/index.rst  2010-08-26 12:41:15 +0000
> >> > > @@ -6,11 +6,12 @@
> >> > >  C++ Programmer's Reference
> >> > >  ##########################
> >> > >
> >> > > -This is the index page for the ``C++`` programmer's reference.
> >> > > +This is the index page for the C++ programmer's reference.
> >> > >  The contents follows the directory structure of DOLFIN.
> >> > >
> >> > >  .. toctree::
> >> > >     :maxdepth: 1
> >> > >
> >> > > +    :ref:`testing <programmers_reference_cpp_mesh_index>`
> >> > > +
> >> >
> >> > You're not supposed to use links in the toctree directive, it's there
> >> > to include other rst files and link stuff together.
> >> > Note the Sphinx will issue a Warning on build if a file is not
> >> > included in a toctree.
> >> >
> >> > http://sphinx.pocoo.org/markup/toctree.html
> >>
> >> Is it possible to make the titles more descriptive than just 'mesh'
> >> and 'la'? I would like it to say things like
> >>
> >>   Meshes
> >>   Linear algebra
>
> I actually used the names 'mesh', 'la' etc. on purpose such that the
> docs will look identical to the directories in the dolfin/dolfin
> source tree, I expect it to be easier to find stuff if we keep it like
> that, but maybe we can have both the short and the long (descriptive)
> name?

Sounds good.

> >> etc.
> >
> > Now I see how it works. I just needed to look for another half second
> > on that link you gave me... :-)
>
> I think this illustrates very well that a 'programmer's reference' as
> documentation is not for the impatient. :)
> It's preferable to just have a demo that works and can be copied... we
> should keep that in mind when writing the docs.

Good point. :-)

--
Anders