Subject: Re: [Fenics] [Branch ~fenics-core/fenics-doc/main] Rev 67: Trying to add a link that doesn't work. What am I missing here?

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 26 Aug 2010 15:18:14 +0200

On 26 August 2010 15:03,  <[email-masked]> wrote:
> ------------------------------------------------------------
> revno: 67
> committer: Anders Logg <[email-masked]>
> 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
>
>
> --
> lp:fenics-doc
> https://code.launchpad.net/~fenics-core/fenics-doc/main
>
> 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

Kristian

>     mesh/index
> -
>
> === modified file 'source/styleguides.rst'
> --- source/styleguides.rst      2010-08-26 10:15:13 +0000
> +++ source/styleguides.rst      2010-08-26 12:41:15 +0000
> @@ -1,7 +1,5 @@
>  .. Style guides for C++, Python, and documentation
>
> -
> -
>  DOLFIN (C++) and FEniCS documentation (Sphinx).
>
>  .. _styleguides:
> @@ -762,7 +760,7 @@
>  """""""""""""""""""""""""
>
>  The Python ``Mesh`` class is automatically generated by Swig from the DOLFIN
> -C++ implementation and
> +C++ implementation and
>
>
>  Using Sphinx autodoc
>
>
>

---

From: Anders Logg <[email-masked]>
Date: Thu, 26 Aug 2010 15:21:33 +0200

> 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

etc.

--
Anders

---

From: Anders Logg <[email-masked]>
Date: Thu, 26 Aug 2010 15:23:25 +0200

> and 'la'? I would like it to say things like

Now I see how it works. I just needed to look for another half second
on that link you gave me... :-)

--
Anders

---

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 26 Aug 2010 15:34:43 +0200

>> and 'la'? I would like it to say things like

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?

> 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

---

From: Anders Logg <[email-masked]>
Date: Thu, 26 Aug 2010 15:35:53 +0200

> that, but maybe we can have both the short and the long (descriptive)

Sounds good.

> should keep that in mind when writing the docs.

Good point. :-)

--
Anders