Subject: Re: [Fenics] [Branch ~fenics-core/fenics-doc/main] Rev 85: Fix some cross referencing, use :ref: not _.

From: Kristian Ølgaard <[email-masked]>
Date: Fri, 27 Aug 2010 14:41:48 +0200

On 27 August 2010 14:33,  <[email-masked]> wrote:
> Merge authors:
>  Marie Rognes (meg-simula)
> ------------------------------------------------------------
> revno: 85 [merge]
> committer: Kristian B. Ølgaard <[email-masked]>
> branch nick: fenics-doc
> timestamp: Fri 2010-08-27 14:30:42 +0200
> message:
>  Fix some cross referencing, use :ref: not _.

Stupid 'bzr ci -m "message".
This should be:

use :ref:`foo` not `foo`_

when creating cross references (and the labels should be added BEFORE
the section headings).
Oh, and this information is also in the styleguides... :)

Kristian

> modified:
>  source/developer.rst
>  source/help.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/developer.rst'
> --- source/developer.rst        2010-08-26 10:14:20 +0000
> +++ source/developer.rst        2010-08-27 12:30:42 +0000
> @@ -21,11 +21,12 @@
>  of all components to ensure interoperability between the components.
>
>  Initially, FEniCS consisted of just two components (DOLFIN and FIAT)
> -but over time, several new components have been added to FEniCS which
> -now consists of more than 10 individual components. Some of these
> -components (like FIAT and UFC) have matured and remain stable, while
> -others are changing at a faster pace. Currently, most development
> -takes place in DOLFIN, the C++ and Python interface of FEniCS.
> +but over time, several new components have been added and FEniCS now
> +consists of more than 10 individual components. Some of these
> +components (such as FIAT and UFC) have matured and reached a more
> +stable state, while others are changing at a faster pace. Currently,
> +most development takes place in DOLFIN, the C++ and Python interface
> +of FEniCS.
>
>  ***************
>  Using Launchpad
> @@ -47,9 +48,9 @@
>  a developer has proven reliable by committing a significant number of
>  high quality contributions.
>
> -An overview of all FEniCS projects on Launchpad can be found
> -`here <https://launchpad.net/fenics-project>`_.
> -`Launchpad pages <launchpad_pages.html>`_ also contains a collection of links to
> +An overview of all FEniCS projects on Launchpad can be found `here
> +<https://launchpad.net/fenics-project>`_.  `Launchpad pages
> +<launchpad_pages.html>`_ also contains a collection of links to
>  important Launchpad pages for the various FEniCS components.
>
>  Below, we describe how Launchpad is used to handle user questions, bug
> @@ -58,14 +59,14 @@
>  User questions
>  ==============
>
> -User questions are discussed on the `Answers <help_answers>`_ pages.
> +User questions are discussed on the :ref:`help_answers` pages.
>  Developers should make sure to join the relevant team for each component so
>  that they will be notified about new user questions.
>
>  Bug reports
>  ===========
>
> -Bug reports are discussed on the `Bugs <help_bugs>`_ pages.
> +Bug reports are discussed on the :ref:`help_bugs` pages.
>  Developers should make sure to join the relevant team for each component so
>  that they will be notified about new bugs.
>
> @@ -88,16 +89,16 @@
>  Code hosting
>  ============
>
> -FEniCS uses Launchpad for hosting code. The code is stored in a
> -`Bazaar <http://bazaar.canonical.com/en/>`_ repository. Each FEniCS
> -component has a Bazaar repository on Launchpad that contains all
> -source code (including the entire development history) for the
> -component. The repository is readable for everyone but write access is
> -only granted to the members of the core team for each component.
> +FEniCS uses Launchpad for hosting code. Each FEniCS component has a
> +`Bazaar <http://bazaar.canonical.com/en/>`_ repository on Launchpad
> +that contains all source code (including the entire development
> +history) for the component. The repositories are readable for
> +everyone, but write access is only granted to the members of the core
> +teams.
>
>  Developers should subscribe to notifications of changes made to the
> -the source code by visiting the repository on Launchpad and clicking
> -the subscribe button.
> +source code by visiting the repository on Launchpad and clicking the
> +subscribe button.
>
>  ************
>  Using Bazaar
> @@ -105,7 +106,7 @@
>
>  Here is a quick reference for `using Bazaar
>  <http://doc.bazaar-vcs.org/bzr.2.0/en/quick-reference/index.html>`_.
> -Below follows a few useful commands for Bazaar.
> +In addition, a few useful commands for Bazaar follow below.
>
>  To set your identity with Bazaar, type
>
> @@ -113,7 +114,7 @@
>
>     bzr whoami "My Name <[email-masked]>"
>
> -To create a new branch (similar to hg clone):
> +To create a new branch:
>
>  .. code-block:: sh
>
> @@ -138,15 +139,15 @@
>     bzr pull <address-to-branch>
>
>  The current development version of each FEniCS component can be
> -obtained directly using a special shortcut available in Bazaar for
> -code hosted on Launchpad:
> +obtained directly using a special shortcut for code hosted on
> +Launchpad:
>
>  .. code-block:: sh
>
>     bzr branch lp:<project-name>
>
> -Thus, one may create a branch of the main DOLFIN repository by running
> -the following command:
> +For instance, one may create a branch of the main DOLFIN repository by
> +typing
>
>  .. code-block:: sh
>
> @@ -160,17 +161,19 @@
>  the core team of that component. Therefore, unless you are a member of
>  the core team, you will not be able to upload any code to the main
>  repository directly. Instead you will have to submit a :ref:`patch
> -<contributing_patches>` or create your own :ref:`branch
> -<contributing_branches>` which will be merged into the main branch by
> -a member of the core team (if accepted).
> +<contributing_patches>`, or create your own :ref:`branch
> +<contributing_branches>`. If the code is accepted, the patch or branch
> +will be merged into the main branch by a member of the core team.
> +
> +.. _contributing_patches:
>
>  Creating a patch
>  ================
>
> -Usually, for simple bug fixes and minor changes, submitting a patch is
> -the simplest method to get code uploaded to the main branch. For
> -instance, to create and submit a patch for DOLFIN, the following
> -procedure should be applied:
> +For simple bug fixes and minor changes, submitting a patch is the
> +simplest method to get code uploaded to the main branch. For instance,
> +to create and submit a patch for DOLFIN, the following procedure
> +should be applied.
>
>  #. Get the current development branch::
>
> @@ -178,21 +181,21 @@
>
>  #. Modify the files.
>
> -#. If your contribution consists of new files, add them to the correct
> -   location in the directory tree::
> +#. If your contribution consists of new files, add those to the
> +   repository::
>
>     bzr add <files>
>
> -   where ``<files>`` is the list of new files. You do not have to take
> -   any action for previously existing files which have been
> -   modified. Do not add temporary or binary files.
> +   where ``<files>`` is the list of new files. Do not add temporary or
> +   binary files. No action is necessary for previously existing files
> +   which have been modified.
>
>  #. Update the author and date information as described in the
> -   :ref:`contributing_license` section.
> +   :ref:`license <contributing_license>` section.
>
>  #. Commit your changes::
>
> -    bzr ci -m "<description>"
> +    bzr commit -m "<description>"
>
>    where ``<description>`` is a short description of what your patch
>    accomplishes.
> @@ -260,7 +263,7 @@
>  ============
>
>  To ease the job for maintainers that will need to read and understand
> -your code, read the `coding style guides <styleguides>`_ that explain
> +your code, read the :ref:`styleguides` that explain
>  how to format your code so that it matches the coding style used for
>  FEniCS.
>
> @@ -290,3 +293,9 @@
>  <http://sphinx.pocoo.org/markup/index.html>`_.  The
>  :ref:`styleguides_sphinx_coding_style` explains what the reST source
>  files should look like.
> +
> +.. _contributing_license:
> +
> +***************
> +License
> +***************
>
> === modified file 'source/help.rst'
> --- source/help.rst     2010-08-25 21:32:45 +0000
> +++ source/help.rst     2010-08-27 12:30:42 +0000
> @@ -10,11 +10,11 @@
>  This page describes how to get in contact to solve problems you might
>  encounter when using FEniCS.
>
> +.. _help_answers:
> +
>  Getting answers
>  ===============
>
> -.. _help_anwers:
> -
>  Questions and answers are handled by the `Launchpad Answers
>  <https://help.launchpad.net/Answers>`_ system.
>
> @@ -34,11 +34,11 @@
>  <https://launchpad.net/~fenics>`_ and the `DOLFIN
>  <https://launchpad.net/~dolfin>`_ teams on Launchpad.
>
> +.. _help_bugs:
> +
>  Reporting bugs
>  ==============
>
> -.. _help_bugs:
> -
>  FEniCS software is under active development. As a consequence, bugs
>  are likely to occur from time to time. In the event that you encounter
>  a bug, please file a bug report using the Launchpad system for
>
>
>

---

From: Marie Rognes <[email-masked]>
Date: Fri, 27 Aug 2010 14:52:27 +0200

> use :ref:`foo` not `foo`_

Ok! I just conformed to what was there. But now I know better -- thanks!

--
Marie

> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>

---

From: Kristian Ølgaard <[email-masked]>
Date: Fri, 27 Aug 2010 15:01:35 +0200

> Ok! I just conformed to what was there. But now I know better -- thanks!

No problem, reST/Sphinx is a learning process for all of us.

Kristian