How to document the quickstart file

Where to find the quickstart files

The quickstart files are located at:

​https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart

Notation

For this documentation:

• Words surrounded by < > are to be defined by the person documenting the project
  • <slug> is the slug name defined on projects_info.csv file
• The project quickstartfile name is <slug>_quickstart.rst for example udig_quickstart.rst
• Words surrounded by @ @ are variables
• Words surrounded by | | are Sphinx variables

Variable	Example	Action
@LOGO_<slug>@	@LOGO_udig@	Gets the logo image of the project if it exists
@OSGEO_KIND_<slug>@	@OSGEO_KIND_udig@	Gets the logo of the kind of project within OSGeo as defined into projects_info.csv
@NAME_<slug>@	@NAME_udig@	Gets the name of the project as defined into projects_info.csv
@QUICKSTART_<slug>@	@QUICKSTART_udig@	Will generate a link to the quickstart if defined into projects_info.csv
@SCREENSHOT_<slug>@	@SCREENSHOT_udig@	Places the screenshot to a given standard size
|version-<slug>|	|version-udig|	Project's version defined into projects_info.csv

Most of those variable points to data collected into a file called projects_info.csv that you can find at the root of the documentation folder: ​https://github.com/OSGeo/OSGeoLive-doc/blob/b1d9cce02535fd75e9b891ebaea379103ab831bb/projects_info.csv

It can be a good idea to fill this file first before writing the quickstart page. How to fill projects_info.csv is explained here : ​https://trac.osgeo.org/osgeolive/wiki/How%20to%20configure%20a%20project%20documentation

quickstart_<slug>.rst File Structure

:Author: <author's name>
:Reviewer: <reviewer name>
:Version: <OSGeoLive version from which this documentation is valid>
:License: Creative Commons Attribution-ShareAlike 3.0 Unported  (CC BY-SA 3.0)



@LOGO_<slug>@
@OSGEO_KIND_<slug>@

********************************************************************************
@NAME_<slug>@ Quickstart
********************************************************************************


.. Writing Tip: Overview section
This section is required and has no heading. Start with a sentence describing what the application is and does. 

This application is a GIS Desktop client for editing and viewing Geospatial data.

.. Writing Tip:
   Next, describe what will be covered in the Quick Start. Choose a few features to show. If you're showing one or two things, write that in sentence format. If it's three or more, use a bullet list. Optionally, you can also manage expectations about the length of the Quick Start - how much time should the user expect to commit to this activity?

This Quick Start describes how to:

* Add a title and subtitle
* Add a link `Web Map Service (WMS) <http://www.opengeospatial.org/standards/wms>`__
* use the standard map tools
* apply color to map features using styling


 .. Writing tip: prerequisites section
     This section is optional. Mention any prerequisites that are required to complete the Quick Start, for example, internet connection or data to test with.

This guide uses some of the sample data included with OSGeo Live. Make sure you can access /usr/local/share/data.

.. contents:: Contents
.. Writing Tip:
  Use headings in your document to automatically generate a table of contents. The headings should start with verbs, and should be the same or similar to what you have said the Quick Start will cover.
  
This is a title
================================================================================

A title has a line with 80 '=', and you  use them to separate big sections of the quickstart

Here a paragraph is starting because of the blank line above.
But this line belongs to this second paragraph.

.. Writing Tip:
  The heading title for the first section is "Start application name". Use numbered steps to describe what to do. Steps start with a verb or action word. Include only one action per step. A description of the expected result is not a new step.
  Use Sphinx inline markup such as :guilabel: for buttons and field names; and :menuselection: for selecting menu items. Also refer to this page to describe elements on the UI https://developers.google.com/style/ui-elements



This is a subtitle
--------------------------------------------------------------------------------

A subtitle has a line with 80 '-', and you  use them to separate sections within the title

The following is an image, and it is being described here

.. image:: /images/projects/<slug>/image_name.png
   :scale: 70 %


The image can be described here also

.. this is a comment, because it does not start with a sphinx command

.. TODO I am using a comment to mention some reminder of things to do



This :menuselection:`Geospatial --> Desktop GIS --> uDig` can be used for a sequence of clicks on menus will look like: `Geospatial ‣ Desktop GIS ‣ uDig`

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

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

   * Has a bullet list (note the blank line and the indentation)
   * This bullet has an image (note the blank line and the indentation)

      .. image:: /images/projects/<slug>/image_name.png
         :scale: 70 %
.. .. Writing Tip - Images:
 For images, use a scale of 50% from a 1024x768 display (preferred) or 70% from a 800x600 display. Markup the graphic with red circles to highlight any particular areas of note on the GUI (if required). Store images here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/images/projects/1024x768/

.. note::
  Notes are optional. You can use them to provide descriptions and background information without getting in the way of instructions. Notes are rendered in the margin in some printed formats.


.. tip::   Tips are optional. You can use them to provide extra useful information or other ways of performing an action like keyboard shortcuts or drag and drop. Tips are rendered in the margin in some printed formats.


The **Bold** and the *Italic*.

The following is for code

::

   Code starts here, (note the blank line between the `::` and the code
   More code

This is not code


The following is `link title <http://this/is/the/external_link.html>`__
(note back ticks ` and the 2 underscores at the end)

The following is an internal link :doc:`../overview/<other_slug>_overview`.




Things to Try
================================================================================

This section is optional. Suggest one or several activities for people to try out on their own.

Present a list of ideas for people to try out:

* Start off very specific with something most people can do based on the materials as presented.
* Continue on with a challenge that involves a small bit of research
* It is **recommended** that research be limited to something that can be
found in documentation packaged on OSGeoLive, as users might not be
connected to the Internet.

Here are some additional challenges for you to try:

#. Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Mauris eget dui vitae estsodales consequat eget vel risus.
   Fusce suscipit lorem sit amet elementum volutpat.
#. Try Praesent pretium mauris id porta convallis.


What Next?
================================================================================

This section is required. Provide links to any further documentation or tutorials. If your project has no further documentation, include a link to your project's website or wiki or include a contact email or mailing list to join.


* the tutorial

   Maybe have a short description of the tutorial. The tutorial or documentation might not be inside the disk, so use this link style:
   
   The link: `link title <http://this/is/the/external_link.html>`__