fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

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?

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

Kristian

> --
> Anders
>