Read the docs, please¶

Quoted paragraphs are created by just indenting them more than the surrounding paragraphs:

Normal paragraph.

   Indented paragraph.

Line blocks are a way of preserving line breaks (the equivalent of using Shift+Enter to break a line in Microsoft Word or LibreOffice Writer):

| These lines are
| broken exactly like in
| the source file.

The markup is quite simple:

• use one asterisk for italics: *text* (the equivalent of using Ctrl+i in Microsoft Word or LibreOffice Writer),
• use two asterisks for strong emphasis (boldface): **text**
• use backquotes for text literals: ``text``

Be aware of some restrictions:

• The markup may not be nested. For example, this markup is wrong: *italics with **bold** inside*
• The text content within the markup may not start or end with whitespace. For example, this markup is wrong: * text*
• The markup must be separated from surrounding text by non-word characters (whitespace or punctuation). Use a backslash-escaped-space to work around that. For example: thisis\ *one*\ word is rendered like thisisoneword.
• If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash.

Subscript is marked with :sub:`subscript text`. Superscript is marked with :sup:`superscript text`.

The chemical formula for molecular oxygen is O\ :sub:`2`.

The chemical formula for pure water is |H2O|.

.. |H2O| replace:: H\ :sub:`2`\ O

List markup is natural: just place an asterisk at the start of a paragraph and indent properly:

*  This is a bulleted list.
*  It has two items, the second
   item uses two lines.

Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:

* this is
* a list

  * with a nested list
  * and some sub-items

* and here the parent list continues

The same goes for numbered lists; they can also be auto-numbered using a # sign:

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Definition lists are created as follows:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

The Sphinx documentation generator provides a more flexible alternative to definition lists (see Glossaries).

The Sphinx ..glossary:: directive contains a reST definition-list-like markup with terms and definitions.

See the following example:

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

The definitions will then be used in cross-references with the :term: role. For example:

The :term:`source directory` for this project is ...

In contrast to regular definition lists, a glossary supports multiple terms per entry and inline markup is allowed in terms. You can link to all of the terms. For example:

.. glossary::

   term 1
   term 2
      Definition of both terms.

When the glossary is sorted, the first term determines the sort order.

To automatically sort a glossary, include the following flag:

.. glossary::
   :sorted:

Field lists are two-column table-like structures resembling database records (label & data pairs). For example:

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer

.. metadata-placeholder

:DC.Title:
   Document title
:DC.Creator:
   Author
:DC.Date:
   Date yyyy-mm-dd
:DC.Description:
   Abstract
:DC.Language:
   en
:DC.Format:
   text/x-rst
:DC.Rights:
   Access rights
:DC.RightsHolder:
   Copyright.

Use `link text <http://example.com/>`_ for inline web links. If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text (with no markup).

You can also separate the link and the target definition, like this:

This is a paragraph that contains `a link`_.

.. _a link: http://example.com/

To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work, the label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels:

• If you place a label directly before a section title, you can reference to it with :ref:`label-name`. Example:

  .. _my-label-ref:
  
  Section to cross-reference
  --------------------------
  
  This is the text of the section.
  
  In the end of this phrase is a reference to the section title, see :ref:`my-label-ref`.
  

  The :ref: role would then generate a link to the section, with the link title being “Section to cross-reference”. This works just as well when section and reference are in different source files.

  Automatic labels also work with figures:

  .. _my-figure-ref:
  
  .. figure:: my-image.png
  
     My figure caption
  

  A reference like :ref:`my-figure-ref` would insert a reference to the figure with link text “My figure caption”.

  The same works for tables that are given an explicit caption using the table directive.

• Labels that aren’t placed before a section title can still be referenced to, but you must provide the text for the link, using this syntax: :ref:`Link text <label-name>`.

Using :ref: is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, and for all builders that support cross-references.

A directive is a generic block of explicit markup.

The directive content follows after a blank line and is indented relative to the directive start.

Basically, a directive consists of a name, arguments, options and content.

Look at this example:

.. contents:: This is my Table of Contents
   :depth: 2

The directive starts with .. followed by one whitespace. The name of the directive is contents (it creates a table of contents). This directive takes one argument: the table of contents’ title (“This is my Table of Contents”). The option depth specifies the number of section levels that are collected in the table of contents.

Options are given in the lines immediately following the arguments and are indicated by the colons. Options must be indented to the same level as the directive content.

Docutils supports the following directives:

• Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (Most themes style only note and warning specially.)
• Images:
  • image - see the images section;
  • figure - an image with caption and optional legend.
• Additional body elements:
  • contents <table-of-contents> - a local table of contents for the sections in the current file only;
  • rubric - a heading without relation to the document’s sections that won’t be included in any table of contents;
  • topic and sidebar - special highlighted body elements;
  • epigraph - a block quote with optional attribution line;
  • container - a container with a custom class, useful to generate an outer ``<div>`` in HTML output.
• Special tables:
  • table - a table with title;
  • csv-table - a table generated from comma-separated values;
  • list-table - a table generated from a list of lists.
• Special directives:
  • include - include reStructuredText from another file;
  • raw - include raw target-format markup, such as LaTeX;
  • class - assign a class attribute to the next element.

To include a table of contents within a given document, use the directive contents. The following example creates a local table of contents with a maximum of two levels (below the level where it is located):

Part II
#######

Chapter 1
*********

.. contents::
   :depth: 2
   :local:

Heading 1
=========

The toctree directive creates a table of contents that collets information from several files. The following example creates a table of contents from the sections of various documents (up to a depth of 3 levels). The :glob: option allows all documents in the ‘chapter2’ folder to be included (sorted according to their name):

.. toctree::
   :glob:
   :maxdepth: 3

   preamble
   chapter1/part1
   chapter1/conclusion
   chapter2/*
   references

reST supports an image directive, used like so:

.. image:: gnu.png
   (options)

The file name given (here gnu.png) must either be relative to the source file, or absolute (which means that they are relative to the top source directory).

For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or as /images/spam.png.

The image size options (width and height) should be specified in points (pt), as that will best support output to different formats (HTML, LaTeX).

A figure consists of image data (including image options), an optional caption (a single paragraph), and an optional legend (arbitrary body elements):

.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

   The legend consists of all elements after the caption.  In this
   case, the legend consists of this paragraph and the following
   table:

   +-----------------------+-----------------------+
   | Symbol                | Meaning               |
   +=======================+=======================+
   | .. image:: tent.png   | Campground            |
   +-----------------------+-----------------------+
   | .. image:: waves.png  | Lake                  |
   +-----------------------+-----------------------+
   | .. image:: peak.png   | Mountain              |
   +-----------------------+-----------------------+

There must be blank lines before the caption paragraph and before the legend. To specify a legend without a caption, use an empty comment (..) in place of the caption.

The table directive associates a title with the following table:

.. table:: User list

   ==========  =========
   First name  Last name
   ==========  =========
   John        Doe
   Jane        Dove
   ==========  =========

A list-table is created from a uniform two-level bullet list:

.. list-table:: User list
   :header-rows:1

   *  - First name
      - Last name
   *  - John
      - Doe
   *  - Jane
      - Dove

A csv-table is created from comma-separated values (either in the document or in an external file):

.. csv-table:: User list
   :header:"First name","Last name"

   "John","Doe"
   "Jane","Dove"

Another example of csv-table, using and external file:

.. csv-table:: Table 1 - Legend of the table goes here...
   :header-rows: 1
   :stub-columns: 1
   :file: ../tables/table1.csv

An exceltable can also be used:

.. exceltable:: Table 1 - Legend of the table goes here...
   :file: ../tables/tables.xls
   :sheet: table1
   :selection: A1:C20
   :header: 1

Using Excel tables requires an additional module sphinxcontrib.exceltable that is an extension for Sphinx, that adds support for including spreadsheets, or part of them, into Sphinx document. It can be installed using pip:

pip install sphinxcontrib-exceltable

Then the project conf.py file needs to be updated:

# Add ``sphinxcontrib.exceltable`` into extension list
extensions = ['sphinxcontrib.exceltable']

Another alternative is xmltable (https://pythonhosted.org/rusty/xmltable.html).

For footnotes, use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading, like so:

Lorem ipsum [#first-footnote-name]_ dolor sit amet [#second-footnote-name]_

.. rubric:: Footnotes

.. [#first-footnote-name] Text of the first footnote.
.. [#fsecond-footnote-name] Text of the second footnote.

You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_).

Standard reST citations are supported:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #.

When the documentation is built using the Sphinx document generator, the citations are “global”, meaning that every citation can be referenced from any .rst files. In this case, a separate file may be created (e.g. a references.rst file).

reST supports “substitutions”, which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:

.. |name| replace:: replacement *text*

or this:

.. |caution| image:: warning.png
             :alt: Warning!

If you want to use some substitutions for all documents, put them into a separate file (e.g. substitutions.txt) and include it into all documents you want to use them in, using the include directive.

Be sure to use a file name extension which different from that of other source files, to avoid Sphinx finding it as a standalone document. For example, use the .rst file extension for the source files, and the .txt file extension for the files which are to be included.

Every explicit markup block which isn’t a valid markup construct is regarded as a comment. For example:

.. This is a comment.

You can indent text after a comment start to form multiline comments:

..
   This whole indented block
   is a comment.

   Still in the comment.

jEdit is a FOSS text editor, written in Java (so it runs in Windows, Mac OS X, Linux, etc.). ReST is among the 211 languages supported natively by jEdit.

Notepad++ is a FOSS text editor for MS Windows OS only.

reStructuredText is not among the languages natively recognised by Notepad++, but it can be added using a `User Defined Language File`_ (see install instructions below the list of available language files).

Follow the link to download the `ReST syntax file`_.

Notepad++ is simpler and more user friendly than jEdit.

ReText is a simple editor that reads your text with MarkDown or HTML markup and saves it as plain text, HTML or PDF. It is written in Python using Qt libraries.

Visual Studio Code is a FOSS text editor, written in TypeScript (so it runs in Windows, Mac OS X, Linux, etc.). ReST is not among the languages natively supported by Visual Studio Code, but it can be added using an extension from LeXtudio.

Sphinx is a Python documentation generator.

It requires Python, which is installed by default in Linux and Mac OS X systems. For Microsoft Windows systems, see Installing Python on Windows if you need help installing Python and two useful installation utilities (easy_install and pip).

After you have Python installed, simply use the following command (in a command window):

easy_install -U Sphinx

Elevated privileges (i.e. administration rights) should not be required.

The Sphinx builder can produce a number of output formats (e.g. HTML, PDF). PDF files can be produced using the LaTeX builder (more complicated) or using the a direct PDF builder called rst2pdf (see below).

rst2pdf is a tool for transforming reStructuredText to PDF using ReportLab. To install rst2pdf on Windows you also need Python because rst2pdf is coded in python.

Rst2pdf uses ReportLab, which can be installed using:

easy_install reportlab

Again, in Windows, there may be a problem with the required Microsoft Visual Studio version. While running setup.py for package installations, Python 2.7 searches for an installed Visual Studio 2008. The solution is to define VS90COMNTOOLS variable to point to Tools directory of Visual Studio:

SET VS90COMNTOOLS=%VS100COMNTOOLS%

The ReST editor for Eclipse is a plug-in for the Eclipse IDE. If Sphinx is installed, it can also be used to create (and build) Sphinx projects from within Eclipse. The following presentation documents the use of the editor.

This ReST editor has several advantages, namely:

• integrated spell-checking using Hunspell4Eclipse
• contextual ReST syntax help
• sections outline rearrangement

You can completely opt out of Jekyll processing by creating a file named .nojekyll in the root of your Page repository and pushing that file to GitHub.

This should only be necessary if your site uses directories that begin with an underscore, as Jekyll sees these as special directories and does not copy them to the final destination.

Since Sphinx puts all the static files in a _static folder, this needs to be done, otherwise the stylesheets, etc, won’t be uploaded to the html site.

The Graphviz extension is included with Sphinx, but the extension must be enabled in the conf.py file:

extensions = ['sphinx.ext.graphviz']

import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']

This code:

.. graphviz::

   digraph {
      "From" -> "To";
   }

has this result:

This code:

.. graphviz::

   digraph Flatland {
   
      a -> b -> c -> g; 
      a  [shape=polygon,sides=4]
      b  [shape=polygon,sides=5]
      c  [shape=polygon,sides=6]
   
      g [peripheries=3,color=yellow];
      s [shape=invtriangle,peripheries=1,color=red,style=filled];
      w  [shape=triangle,peripheries=1,color=blue,style=filled];
      
      }

has this result:

Numerous examples are available online:

• https://en.wikipedia.org/wiki/DOT_(graph_description_language)
• http://www.graphviz.org/pdf/dotguide.pdf
• http://graphs.grevian.org/example.html

The module is installed with the following command:

pip install sphinxcontrib-plantuml

The extension must be enabled in the conf.py file:

extensions = ['sphinxcontrib.plantuml']

The path to the PlantUML file may have to be specified (assuming that Java itself is already in the search path):

plantuml = 'java -jar ../utils/plantum.jar'

PlantUML requires Graphviz and an environment variable may have to be defined, pointing to the dot executable. For example (in Linux or OS-X):

setenv GRAPHVIZ_DOT /usr/local/bin/graphviz/dot
export GRAPHVIZ_DOT

/etc/profile.d/*.sh

export GRAPHVIZ_DOT=/usr/bin/dot

In the Sphinx reST documents, simply begin the PlantUML code with the uml directive.

This is the code for the example above:

.. uml:: 
   
   @startuml
   user -> (use PlantUML)

   note left of user
      Hello!   
   end note
   @enduml

Another example:

This is the code for the example above:

.. uml::
   
   @startuml 
   Alice -> Bob: Hi!
   Alice <- Bob: How are you?
   @enduml

This is the diagram generated by the Sphinx PlantUML extension.

This is the code for example above.

.. uml::

      @startuml
      
      'style options 
      skinparam monochrome true
      skinparam circledCharacterRadius 0
      skinparam circledCharacterFontSize 0
      skinparam classAttributeIconSize 0
      hide empty members
      
      Class01 <|-- Class02
      Class03 *-- Class04
      Class05 o-- Class06
      Class07 .. Class08
      Class09 -- Class10
      
      @enduml

Note that in docutils / Sphinx, @startuml and @enduml could be omitted. However, it is useful to keep these lines: is necessary, PlantUML can be used (outside Sphinx) to generate the PNG image files with the diagrams directly from the text file; also, if editing the code in Eclipse, the PlantUML diagrams can be previewed without the necessity of building the documentation.

The image was exported using the Eclipse PlantUML plug-in. It it static, but can be resized...

.. uml::

      @startuml
      
      'style options 
      skinparam monochrome true
      skinparam circledCharacterRadius 0
      skinparam circledCharacterFontSize 0
      skinparam classAttributeIconSize 0
      hide empty members
      
      class Car
      
      Driver - Car : drives >
      Car *- Wheel : have 4 >
      Car -- Person : < owns
      
      @enduml

To declare fields and methods, you can use the symbol ”:” followed by the field’s or method’s name. The system checks for parenthesis to choose between methods and fields.

.. uml::

      @startuml
      
      'style options 
      skinparam monochrome true
      skinparam circledCharacterRadius 9
      skinparam circledCharacterFontSize 8
      skinparam classAttributeIconSize 0
      hide empty members

      abstract class AbstractClass {
        - privateField
        + publicField
        # protectedField
        ~ packagePrivateField
        - privateMethod()
        + publicMethod()
        # protectedMethod()
        ~ packagePrivateMethod()
         }
  
      class Dummy {
        {static} staticID
        {abstract} void methods()
         }
      
      class Flight {
         flightNumber : Integer
         departureTime : Date
         }
      
      package "Classic Collections" {
         
         abstract class AbstractList
         abstract AbstractCollection
         interface List
         interface Collection
         
         List <|-- AbstractList
         Collection <|-- AbstractCollection
         
         Collection <|- List
         AbstractCollection <|- AbstractList
         AbstractList <|-- ArrayList
         
         class ArrayList {
           Object[] elementData
           size()
            } 
      }
      
      enum TimeUnit {
        DAYS
        HOURS
        MINUTES
      }
        

      class Student {
        Name
      }
      Student "0..*" -- "1..*" Course
      (Student, Course) .. Enrollment
      
      class Enrollment {
        drop()
        cancel()
      }

      @enduml

This is generated by the Sphinx PlantUML extension.

The image was exported using the Eclipse PlantUML plug-in. It it static, but can be resized...

There are two syntaxes to create activity diagrams. The example utilises the new syntax (which is still incomplete).

.. uml::

   @startuml
   
   start
   
   :first activity;
   
   :second activity
    with a multiline 
    and rather long description;
   
   :another activity;
   
   note right
     After this activity,
     are two 'if-then-else' examples. 
   end note
   
   if (do optional activity?) then (yes)
      :optional activity;
   else (no)
   
      if (want to exit?) then (right now!)
         stop
      else (not really)
      
      endif
   
   endif   
      
   :third activity;
   
   note left
     After this activity,
     parallel activities will occur. 
   end note
   
   fork
      :Concurrent activity A;
   fork again
      :Concurrent activity B1;
      :Concurrent activity B2;
   fork again
      :Concurrent activity C;
      fork
      :Nested C1;
      fork again
      :Nested C2;
      end fork
   end fork
   
   repeat 
      :repetitive activity;
   repeat while (again?)
   
   while (continue?) is (yes, of course)
     :first activity inside the while loop;
     :second activity inside the while loop;
   endwhile (no)
   
   stop
   
   @enduml

The image was exported using the Eclipse PlantUML plug-in. It it static, but can be resized...

Generated by the Sphinx PlantUML extension.

The image was exported using the Eclipse PlantUML plug-in. It it static, but can be resized...

The module is installed with:

pip install sphinxcontrib-bibtex

The Sphinx project conf.py file must be altered to include:

extensions = ['sphinxcontrib.bibtex']

In the document, use the following syntax:

See :cite:`Strunk1979` for an introduction to stylish blah, blah...

And place the directive at the end of the document:

.. bibliography:: references.bib

The references.bib file should contain a BibTex bibliography, including an entry for:

@BOOK{Strunk1979,
  title = {The Elements of Style},
  publisher = {Macmillan},
  year = {1979},
  author = {Strunk, Jr., William and E. B. White},
  edition = {Third}
}

Consider a typical hierarchy:

• The ‘blue’ actor only works and knows the ‘green’ actors.
• Each ‘green’ actor works with a distinct group of ‘yellow’ actors.
• The blue actor’s responsibility is to collate the green actors’ contributions (changes) and to resolve any conflicts between different changes proposed by distinct green actors.
• Each green actor’s responsibility is similar, with regard to the yellow actors.

This hierarchy is a particular type of network (...a directed acyclic network or ‘tree’).

It can be viewed as 3 distinct “networks of trust”.

The concept of “network of trust” simplifies the work:

• The blue actor trusts the green actor to review the work done by his yellow co-workers.
  • From the blue actor’s point of view, the specific configuration of each ‘green & yellow’ network is irrelevant.
  • It is also irrelevant whether the all network is really a tree (or if a given yellow actor participates in two distinct subnetworks).
• Each actor needs only trust (and interact with) his immediate neighbourhood:
  • The green actor accepts any upstream changes approved by his blue neighbour.
  • The green actor approves (or declines) changes made by his yellow neighbours (or resolves conflicts between different changes).
• By definition, the blue actor can directly commit changes to his own blue repository of information. So can the green actors to their own green repositories.
• Each actor can also ‘pull’ into his repository any changes that his immediate neighbours have made.

The initial workflow is depicted below:

1. Mr Blue creates the original repository.
2. Mr Green clones Blue’s repository
3. thus obtaining a working copy.

The repository is then distributed to all the team:

1. Each yellow actor can obtain their working copy, by cloning Green’s repository.
2. Mr Green’s repository is now the master repository for all the yellow actors.
3. Mr Blue’s repository is now the upstream repository for all the yellow actors.

The repositories must be explicitly synced. For example, suppose that:

1. Mr Green changed some files and then made a ‘local commit’. Green’s repository now has a new revision (which does not exist in any other repository).
2. One of the yellow actors synchronises the local working copy everyday, to ensure that he has the latest files. His local working copy is updated with the latest revision made by Mr Green to the master repository.
3. The other yellow actors didn’t update their local working copies, and still have the previous revision.
4. Meanwhile, Mr Blue is unaware of any changes in the downstream repositories.

Changes can also by propagated upstream. Suppose that:

1. A yellow actor has changed some files and made a ‘local commit’. The local repository has a new revision (jargon: ‘the local repository is one commit ahead of the master repository’).
2. The yellow actor notifies Mr Green and asks him to merge the changeset into Mr Green’s repository (jargon: ‘sends Mr Green a pull request’).
3. Mr Green reviews the changes, approves them (or not...) and merges the changeset into his own repository.
4. Meanwhile, Mr Blue is still unaware of any changes in the downstream repositories (he has received no pull requests).

When the work assigned to Mr Green’s team is ready:

1. Mr Green send a ‘pull request’ to Mr Blue.
2. Mr. Blue reviews and accepts the changes, and updates his repository.
3. Everyone else can synchronise their repositories to the latest version.

Consider the following network:

• Mr Grey is the technical writer responsible for the English version of the ‘User Manual’ and ‘Project Handbook’. Mr Grey is also responsible for the templates and stylesheets that will be used in the various documents.
• Mr Πράσινος is responsible for the Greek language version.
• Mr Жълт is responsible for the Bulgarian language version.
• Mr Azul is responsible for the Portuguese language version.

When the translation process begins:

1. Mr Grey creates a repository with the English documents (e.g. one file per chapter) and with the image files (e.g. the application screenshots), templates and stylesheets required to build the final document.

2. Messrs Πράσινος, Жълт and Azul all clone the English language repository and create their own working copies.

3. Each of them also creates a local branch: a replica of the files so that each can work on translating the text to their own language while reusing the image files and the stylesheet.

   In this example, the English version is the trunk. Each localised version is a branch.

When new documents are ready to be translated:

1. Mr Grey completes a new chapter and commits it to the repository.

   Mr Grey also changes some of the images.

   A new revision is now available.

2. Messrs Πράσινος, Жълт and Azul synchronise their working copies with the master repository (only the trunk is updated).

3. Each of them also updates the local branch.

What if Mr Πράσινος detects some spelling errors in the English version?

1. Mr Πράσινος changes the English files in the trunk, makes a local commit and notifies Mr Grey.

2. Mr Grey reviews the changes and accepts the pull request.

   The last revision of the master repository now includes the changes made by Mr Πράσινος (but not the Greek branch).

3. Messrs Жълт and Azul synchronise their working copies with the master repository.

   The working copies of the trunk are updated. Each team member must update their specific local branches.

Branches can function as different versions...

1. Mr Πράσινος changes the default stylesheet, including some styles that improve its use with the Greek alphabet.

   Changes are made only in the Greek language branch.

2. Mr Жълт makes a similar change, due to the Cyrillic alphabet.

   Changes are made only to the Bulgarian language branch.

3. Mr Azul dislikes the colour of chapter headings and changes the stylesheet in the Portuguese language branch.

   Mr Azul decides to submit the changes to Mr Grey, so that the trunk can also be changed.

4. Mr Grey reviews the changes made by Mr Azul, but does not accept them.

   The trunk stylesheet is not changed.

When you first setup Git, set up your user name and email address so your first commits will record them properly:

git config --global user.name "My Name"
git config --global user.email "user@email.com"

Initialise a new git repository, then stage all the files in the directory and finally commit the initial snapshot:

$ git init
$ git add .
$ git commit -m 'initial commit'

Create a new branch named feature_A, check it out so it is the active branch, then edit and stage some files and finally commit the new snapshot:

$ git branch feature_A
$ git checkout feature_A
$ (edit files)
$ git add (files)
$ git commit -m 'add feature A'

Switch back to the master branch, reverting the feature_A changes you just made, then edit some files and commit your new changes directly in the master branch context.:

$ git checkout master
$ (edit files)
$ git commit -a -m 'change files'

Merge the feature_A changes into the master branch context, combining all your work. Finally delete the feature_A branch.:

$ git merge feature_A
$ git branch -d feature_A

Git configuration, and repository initialisation & cloning.

command	description
git config [key] [value]	set a config value in this repository
git config global [key] [value]	set a config value globally for this user
git init	initialise an existing directory as a Git repository
git clone [url]	clone a Git repository from a URL
git help [command]	get help on any Git command

Working with snapshots and the Git staging area.

command	description
git status	show the status of what is staged for your next commit and what is modified in your working directory
git add [file]	add a file as it looks now to your next commit (stage)
git reset [file]	reset the staging area for a file so the change is not in your next commit (unstage)
git diff	diff of what is changed but not staged
git diff --staged	diff of what is staged but not yet committed
git commit	commit your staged content as a new commit snapshot
git rm [file]	remove a file from your working directory and unstage

Working with Git branches and with the stash.

command	description
git branch	list your branches. a * will appear next to the currently active branch
git branch [branch-name]	create a new branch at the current commit
git checkout [branch]	switch to another branch and check it out into your working directory
git checkout -b [branch]	create a branch and immediately switch to it
git merge [branch]	merge another branch into your currently active one and record the merge as a commit
git log	show commit logs
git stash	stash away the currently uncommitted modifications in your working directory temporarily
git stash apply	re-apply the last stashed changes

Fetching, merging and working with updates from another repository.

command	description
git remote add [alias] [url]	add a git URL as an alias
git fetch [alias]	fetch down all the branches from that Git remote
git merge [alias]/[branch]	merge a branch on the server into your currently active branch to bring it up to date
git push [alias] [branch]	push the work on your branch to update that branch on the remote git repository
git pull	fetch from the URL tracked by the current branch and immediately try to merge in the tracked branch

Examining logs, diffs and object information.

command	description
git log	show the commit history for the currently active branch
git log branchB..branchA	show the commits on branchA that are not on branchB
git log --follow [file]	show the commits that changed file, even across renames
git diff branchB...branchA	show the diff of what is in branchA that is not in branchB
git show [SHA]	show any object in Git in human-readable format

To contribute to a project that is hosted on GitHub (or another repository hosting site, such as BitBucket) you can fork the project online, then clone your fork locally, make a change, push back to GitHub and then send a pull request, which will email the maintainer.:

fork project on github
$ git clone https://github.com/my-user/project
$ cd project
$ (edit files)
$ git add (files)
$ git commit -m 'Explain what I changed'
$ git push origin master
go to github and click ‘pull request’ button

A place to hide modifications made to the workspace, while working on something else. (The stash area is not required in a “normal” workflow.)

The local working area.

The “index”– or “staging area” – holds a snapshot of the content of the working area, and it is this snapshot that is taken as the contents of the next commit.

A local area under version control. Typical branches: master, dev (for local development), feature_x, bugfix_y

Typically a remote area under version control. Default name is ‘origin’. Typical branches here: master, shared_feature_x, release_y.

Configure kdiff3 as the merge tool (in Windows):

$ git config --global mergetool.kdiff3.path 'C:\Program Files (x86)\KDiff3\kdiff3.exe'
$ git config --global merge.tool kdiff3

Invoke kdiff3:

$  git mergetool <file>

This operation will discard all changes in the local repository:

$ git reset --hard HEAD
$ git pull

A pattern can be used. For example, this will add any new or untracked *.rst file:

$ git add $(git ls-files --other *.rst)

This will remove multiple files that have already been deleted from disk:

$ git rm $(git ls-files --deleted)

Alternatively, edit the .git\config file, and add the following lines:

[alias]
   rma = !git ls-files --deleted -z | xargs -0 git rm

Then run the command using the alias:

$git rma

Special character and spaces in file names can be problematic. To disable quotes file names (Windows Unicode Support), use:

$  git config [--global] core.quotepath off

1. Install both Git and the Dropbox client application on the computer.

2. Go to the local Dropbox folder and create a bare repository. Open a Git Bash window:

   $ cd ~/Dropbox
   $ mkdir -p remoteRepos/ProjectXPTO
   $ git init –bare remoteRepos/ProjectXPTO
   

3. Go to the local project folder, and start a local git repository:

   $ cd ~/localRepos/ProjectXPTO
   $ git init .
   $ git add .
   $ git commit –all -m "Initial commit"
   

4. Link the local repository to the “remote” repository on the Dropbox folder:

   $ git remote add dropbox /Dropbox/remoteRepos/ProjectXPTO/
   

5. Push all the local changes to the “remote” repository:

   $ git push dropbox master
   

1. Again, both Git and the Dropbox application must be installed and the Dropbox folders must be synced.

2. Then, clone the “remote” repository with:

   $ cd ~/otherMachine/ProjectXPTO
   $ git clone -o dropbox /Dropbox/remoteRepos/ProjectXPTO/
   

1. Changes to the local project can be pushed back to the “remote”:

   $ git commit –all -m "Changes made!"
   $ git push dropbox master
   

1. To sync the local copy with the “remote” repository:

   $ git pull dropbox master
   

Mylyn can use a local task repository or a remote one.

If the remote task repository is associated with an issue tracking system, a ‘connector’ is required. By default, a Bugzilla connector is included with Mylyn (and Eclipse).

A long list of different connectors is available at http://wiki.eclipse.org/Mylyn/Extensions. It includes connectors for Trac and Redmine, GitHub and Bitbucket, etc...

Connectors can be installed in different ways:

1. Some (stable) connectors are available through the Mylyn Task List window:

   • Add repository > Install more connectors...

   For example, the Trac connector is available in this list.

2. Other connectors (alpha versions, etc) can be installed using the standard plug-in install procedure inside Eclipse:

   • Goto Help > Install new software...
   • Providing the link to the update site (available in the connector description in the Mylyn/Extensions wiki page).

   This is the case for:

   • The Bitbucket Mylyn Connector, which is alpha status and is available at http://www.mylynbitbucketconnector.xpg.com.br/update
   • The GitHub Connector (egit-github), also in alpha status and available at http://download.eclipse.org/egit/github/updates-nightly

Specifically for my projects, two connectors are required:

• The Trac connector
• The Bitbucket connector (currently 2013.10.21 not working properly due to an identified but not yet fixed bug)

A basic tutorial on Mylyn is available at: http://www.vogella.com/articles/Mylyn/article.html.

A generic introduction is available at: http://www.youtube.com/watch?v=bSYVpjom4pU

It is not clear if the PlantUML plug-in works with the Eclipse Kepler version (4.3).

The update site for Eclipse Juno (4.2) is:

http://plantuml.sourceforge.net/updatesitejuno/

Let’s try it. It’s working!

Note that the Graphviz software must be installed.

1. Goto Window > Show View > Other > PlantUML to open a visualisation tab.

2. Insert the following text into a document (or inside a multiline code comment):

   @startuml
   
      user -> (use PlantUML)
   
      note left of user
         Hello!
      end note
   
   @enduml
   

3. The diagram will be displayed the the PlantUML visualisation pane, where it can be exported to a graphic file.

1. Start Eclipse

2. Goto Help > Install New Software

3. Press Add... to add a new resource and specify a name and the URL (the link below is for the Eclipse Kepler version):

   NAME: Papyrus
   URL:  http://download.eclipse.org/modeling/mdt/papyrus/updates/releases/kepler
   

Tutorial on the Eclipse Modelling Framework (not on Papyrus, but it will be useful later on): http://www.vogella.com/articles/EclipseEMF/article.html

Python 2.7 is assumed to be installed.

1. Start Eclipse

2. Goto Help > Install New Software

3. Press Add... to add a new resource and specify a name and the URL:

   NAME: PyDevEnv
   URL:  http://pydev.org/updates
   

4. Select PyDev and PyDev Mylyn Integration from the list and press Next.

5. Acept the licence terms when the download ends.

6. Restart Eclipse.

1. Goto Window > Preferences > PyDev > Editor > Interpreter Python
2. Eclipse can configure the options automatically (press Auto Config) or the location of the Python interpreter can be specified. (in Linux, usually that would be /usr/bin/python)
3. Press OK to finish the configuration.

1. Goto File > New > Project and select ‘Pydev project’
2. Create a new file (goto File > New > File) HelloWorld.py
3. Add the code
4. Press Run or Ctrl + F11

Python projects will be associated with a “Python perspective”, i.e. a customised layout of windows and GUI elements.

References: 1 ; 2 .

A generic tutorial covering all the above steps is available at: http://www.vogella.com/articles/Python/article.html

This plug-in can be installed through the Eclipse Marketplace (Help > Eclipse Marketplace...) or through the standard plug-in installation:

1. Goto Help > Install new software...
2. Add the project update site: http://resteditor.sourceforge.net/eclipse
3. Select the ReST Editor plug-in

The plug-in is configured under Window > Preferences > ReST Editor.

The following options are important:

• The preferred section markers order, that will be used to automatically correct any improper sequence: #*=-^”
• The tab length (3) and the option to insert spaces instead of tabs.
• The spell checking options (see Hunspell4Eclipse).

The ReST Editor plug-in can be used to create a new Sphinx project:

1. Goto File > New > Project > ReST Editor > Sphinx project
2. Follow the wizard’s instructions...

If Sphinx is installed, then ReST documents can be built from within Eclipse (using the make.bat or the makefile).

This plug-in can be installed through the Eclipse Marketplace (Help > Eclipse Marketplace...) or through the standard plug-in installation procedure.

No dictionaries are included. The plug-in uses Hunspell or Myspell dictionaries. These are also used by LibreOffice, and are available in the extensions directory (for example, “C:Program Files (x86)LibreOffice 4.0shareextensions”).

Preferences per workspace can be configured in: 1. Preferences - General - Editors > TextEditors > Spelling

1. Select Hunspell4Eclipse
2. Browse... and select a dictionary(.dic) file

Useful links:

• https://code.google.com/p/hunspell4eclipse/
• https://wiki.mozilla.org/L10n:Dictionaries

• Right-click on the make.bat file and goto Run as > Run Configurations...
• Select the option Sphinx (via make file)
• Create a new configuration: * Specify the working directory, for example ${project_loc}/docs * Specify the type of Sphinx output, for example html

The new configuration will be accessible through the button bar (in the Run button drop-down options).

The console pane will show the Sphinx output.

Dependencies (for the stable version StatET 3.3 in Eclipse 4.3):

To install the R Packages of RJ 1.1 (StatET 3.0-3.3), use the following command in a common R Term console:

install.packages(c("rj", "rj.gd"), repos="http://download.walware.de/rj-1.1")

In Eclipse, use the standard plug-in installation procedure:

1. Goto Help > Install New Software

2. Press Add... to add a new resource and specify a name and the URL:

   NAME: StatET
   URL:  http://download.walware.de/eclipse-4.3
   

3. For most users it is recommend to select only StatET (and Add-ons/Utilities, if desired), but no Libraries; the dependencies are resolved automatically.

• Eclipse and StatET – a working environment for R
• A guide to Eclipse and the R plug-in StatET

• For a specific project: File > Properties > Text file encoding
• Goto Window > Preferences > General > Content types and change the Default encoding for each type.
• Goto Window > Preferences > General > Workspaces > Text file encoding

• Goto Window > Preferences > General > Editors > Text Editors > Show print margin (80)