Changes between Initial Version and Version 1 of How to document the quickstart file


Ignore:
Timestamp:
12 Apr 2018 12:57:42 (19 months ago)
Author:
cvvergara
Comment:

adding a how to write a quickstart

Legend:

Unmodified
Added
Removed
Modified
  • How to document the quickstart file

    v1 v1  
     1[[PageOutline(1-2)]]
     2
     3= How to document the quickstart file
     4
     5== Where to find the quickstart files
     6
     7The overview files are located at:
     8
     9https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart
     10
     11== Notation
     12
     13For this documentation:
     14
     15*  Words surrounded by `< >` are to be defined by the person documenting the project
     16  * `<slug>` is the slug name defined on `projects_info.csv` file
     17* The project overview file name is `<slug>_overview.rst` for example `udig_overview.rst`
     18* Words surrounded by `@ @` are variables
     19* Words surrounded by `| |` are Sphinx variables
     20
     21
     22
     23||= Variable =||= Example =||= Action =||
     24|| @LOGO_<slug>@ || `@LOGO_udig@` || Gets the logo image of the project  if it exists ||
     25|| @OSGEO_KIND_<slug>@ || `@OSGEO_KIND_udig@` || Gets the logo of the kind of project within OSGeo as defined on the `projects_info.csv`||
     26|| @NAME_<slug>@ || `@NAME_udig@` || Gets the name of the project as defined on the `projects_info.csv` ||
     27|| @QUICKSTART_<slug>@ || `@QUICKSTART_udig@` || Will generate a link to the quickstart if defined on the `projects_info.csv`  ||
     28|| @SCREENSHOT_<slug>@ || `@SCREENSHOT_udig@` || Places the screenshot to a given standard size ||
     29|| |version-<slug>| || `|version-udig|` || Project's version defined on the `projects_info.csv`
     30
     31
     32= `quickstart_<slug>.rst` File Structure
     33
     34{{{
     35:Author: <author's name>
     36:Reviewer: <reviewer name>
     37:Version: <OSGeoLive version from which this documentation is valid>
     38:License: Creative Commons Attribution-ShareAlike 3.0 Unported  (CC BY-SA 3.0)
     39
     40
     41
     42@LOGO_<slug>@
     43@OSGEO_KIND_<slug>@
     44
     45********************************************************************************
     46@NAME_<slug>@ Quickstart
     47********************************************************************************
     48
     49
     50First sentence defines what the application does.
     51You may also need to include a sentence of two describing the domain.
     52Eg: For a Business Intelligence application, you should describe what
     53Business Intelligence is.
     54
     55This Quick Start describes how to:
     56
     57* Add a title and subtitle
     58* Add a link
     59* `Web Map Service (WMS) <http://www.opengeospatial.org/standards/wms>`__
     60* use the standard map tools
     61* apply color to map features using styling
     62
     63.. contents:: Contents
     64 
     65This is a title
     66================================================================================
     67
     68A title has a line with 80 '=', and you  use them to separate big sections of the quickstart
     69
     70Here a paragraph is starting because of the blank line above.
     71But this line belongs to this second paragraph.
     72
     73This is a subtitle
     74--------------------------------------------------------------------------------
     75
     76A subtitle has a line with 80 '-', and you  use them to separate sections within the title
     77
     78The following is an image, and Its being described here
     79
     80.. image:: /images/projects/<slug>/image_name.png
     81   :scale: 70 %
     82
     83
     84The image can be described here also
     85
     86.. this is a comment, because it does not start with a sphinx command
     87
     88.. TODO I am using a comment to mention some reminder of things to do
     89
     90
     91
     92This :menuselection:`Geospatial --> Desktop GIS --> uDig` can be used for a sequence of clicks on menus will look like: `Geospatial ‣ Desktop GIS ‣ uDig`
     93
     94* This is a bulleted list.
     95* It has two items, the second
     96  item uses two lines. (note the indentation)
     97
     981. This is a numbered list.
     992. It has two items too.
     1003. This numbered list
     101
     102   * Has a bullet list (note the blank line and the indentation)
     103   * This bullet has an image (note the blank line and the indentation)
     104
     105      .. image:: /images/projects/<slug>/image_name.png
     106         :scale: 70 %
     107
     108
     109.. note::
     110  Notes are used to provide descriptions and background information without
     111  getting in the way of instructions. Notes will likely be rendered in
     112  the margin in some printed formats.
     113
     114
     115.. tip::   Tips are used to provide extra useful information, and will
     116  likely be rendered in the margin in some printed formats.
     117
     118
     119The **Bold** and the *Italic*.
     120
     121The following is for code
     122
     123::
     124
     125   Code starts here, (note the blank line bewtween the `::` and the code
     126   More code
     127
     128This is not code
     129
     130
     131The following is `link title <http://this/is/the/external_link.html>`__
     132(note back ticks ` and the 2 underscores at the end)
     133
     134The following is an internal link :doc:`../overview/<other_slug>_overview`.
     135
     136
     137
     138
     139Things to Try
     140================================================================================
     141
     142This section is highly recommended, and should provide pointers further things to try.
     143
     144Present a list of ideas for people to try out:
     145
     146* Start off very specific with something most people can do based on the materials as presented.
     147* Continue on with a challenge that involves a small bit of research
     148* It is **recommended** that research be limited to something that can be
     149found in documentation packaged on OSGeoLive, as users might not be
     150connected to the Internet.
     151
     152Here are some additional challenges for you to try:
     153
     154#. Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     155   Mauris eget dui vitae estsodales consequat eget vel risus.
     156   Fusce suscipit lorem sit amet elementum volutpat.
     157#. Try Praesent pretium mauris id porta convallis.
     158
     159
     160What Next?
     161================================================================================
     162
     163
     164This section is highly recommended, please provide links to further tutorials and other documentation.
     165
     166
     167* the tutorial
     168
     169   Maybe have a short description of the tutorial. The tutorial or documentation might not be inside the disk, so use this link style:
     170   
     171   The link: `link title <http://this/is/the/external_link.html>`__
     172
     173
     174}}}
     175
     176