Changes between Version 9 and Version 10 of How to document the quickstart file


Ignore:
Timestamp:
19 Nov 2019, 19:51:32 (4 years ago)
Author:
flicstar
Comment:

Removed the 'Example file structure' section because it is duplicated in the template.

Legend:

Unmodified
Added
Removed
Modified

  • How to document the quickstart file

    v9 v10  
    11[[PageOutline(1-2)]]
    22
    3 = How to document the quickstart file
     3= How to document the quickstart
    44
    55== What is a quickstart?
    … …  
    1414
    1515
    16 == Data for sample procedures
    17 In order to reduce disk space and maintain consistency between applications, all Quickstarts should make use of the common #Example_Datasets that are loaded with OSGeoLive. If the datasets don't cover your requirements, discuss this with us and we may add another suitable common dataset.
    18 
    19 == How to write a quickstart
     16== Writing a quickstart
    2017
    2118Write in a friendly, conversational style similar to the way a teacher would talk a class through an example. The QuickStarts for R and GeoServer do this very well.
    2219
    23 Write in reStructured text (reSt) format. Docutils provides a good reference for writing in reSt format [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]
     20* Write in reStructured text (reSt) format. Docutils provides a good reference for writing in reSt format [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]
     21* Documentation is built using sphinx. You can use a browser-based sphinx editor to preview your work. For example, https://livesphinx.herokuapp.com/
    2422
    25 Documentation is built using sphinx. You can use a browser-based sphinx editor to preview your work. For example, https://livesphinx.herokuapp.com/
    26 
    27 === Notes about markup
    28 
    29 Section headings - Use 80 characters above and below the quickstart title. You need 80 because the title uses a slug and we don't know how many characters the application name is.
    30 All other section headings characters need only be as long as the heading.
    31 
    32 Sphinx inline markup:
    33 * use :guilabel: for buttons and field names
    34 * use :menuselection: for selecting menu items. This typically looks something like, From the menu, choose :menuselection:`View --> Zoom --> Zoom Out`.
    35 
    36 Use the asterisk symbol for unordered lists, and the hash symbol for numbered steps.
    37 
    38 Use the following for images:
    39     .. image:: /images/projects/<slug>/image_name.png
    40          :scale: 70 %
    41 
    42 Links:
    43 * External `link title <http://this/is/the/external_link.html>`__ (note the back ticks ` and the 2 underscores at the end)
    44 * Internal :doc:`../overview/<other_slug>_overview`.
    45 
    46 
    47 Code block
    48 
    49 ::
    50 
    51    Code starts here, (note the blank line between the `::` and the code
    52    More code
    53 
    54 
    55 === OSGeoLive notation
    56 
    57 *  Words surrounded by `< >` are to be defined by the person documenting the project
    58   * `<slug>` is the slug name defined on `projects_info.csv` file
    59 * The project quickstartfile name is `<slug>_quickstart.rst` for example `udig_quickstart.rst`
    60 * Words surrounded by `@ @` are variables
    61 * Words surrounded by `| |` are Sphinx variables
    62 
    63 ||= Variable =||= Example =||= Action =||
    64 || @LOGO_<slug>@ || `@LOGO_udig@` || Gets the logo image of the project  if it exists ||
    65 || @OSGEO_KIND_<slug>@ || `@OSGEO_KIND_udig@` || Gets the logo of the kind of project within OSGeo as defined into  `projects_info.csv`||
    66 || @NAME_<slug>@ || `@NAME_udig@` || Gets the name of the project as defined into `projects_info.csv` ||
    67 || @QUICKSTART_<slug>@ || `@QUICKSTART_udig@` || Will generate a link to the quickstart if defined into `projects_info.csv`  ||
    68 || @SCREENSHOT_<slug>@ || `@SCREENSHOT_udig@` || Places the screenshot to a given standard size ||
    69 || |version-<slug>| || `|version-udig|` || Project's version defined into `projects_info.csv`
    70 
    71 
    72 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 ]
    73 
    74 
    75 It is a good idea to fill the projects_info.csv file first before writing your quickstart. How to fill `projects_info.csv` is explained here : https://trac.osgeo.org/osgeolive/wiki/How%20to%20configure%20a%20project%20documentation
    76 
     23Make a copy of the quickstart template and use it as a base to create your own quickstart: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst.
    7724
    7825=== Writing tips
    … …  
    11259
    11360This 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.
     61=== Notes about markup
    11462
    115 == Example file structure
    116 The quickstart template which includes the basic structure is here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst.
    117 Take a copy of this file and use it to create your own quickstart.
     63Section headings - Use 80 characters above and below the quickstart title. You need 80 because the title uses a slug and we don't know how many characters the application name is.
     64All other section headings characters need only be as long as the heading.
     65
     66Sphinx inline markup:
     67* use :guilabel: for buttons and field names
     68* use :menuselection: for selecting menu items. This typically looks something like, From the menu, choose :menuselection:`View --> Zoom --> Zoom Out`.
     69
     70Use the asterisk symbol for unordered lists, and the hash symbol for numbered steps.
     71
     72Use the following for images:
     73    .. image:: /images/projects/<slug>/image_name.png
     74         :scale: 70 %
     75
     76Links:
     77* External `link title <http://this/is/the/external_link.html>`__ (note the back ticks ` and the 2 underscores at the end)
     78* Internal :doc:`../overview/<other_slug>_overview`.
    11879
    11980
    120 {{{
    121 :Author: <author's name>
    122 :Reviewer: <reviewer name>
    123 :Version: <OSGeoLive version from which this documentation is valid>
    124 :License: Creative Commons Attribution-ShareAlike 3.0 Unported  (CC BY-SA 3.0)
     81Code block
     82
     83::
     84
     85   Code starts here, (note the blank line between the `::` and the code
     86   More code
     87
     88=== Data for sample procedures
     89To reduce disk space and maintain consistency between applications, all Quickstarts should make use of the common #Example_Datasets that are loaded with OSGeoLive. If the datasets don't cover your requirements, discuss this with us and we may add another suitable common dataset.
     90
     91=== OSGeoLive notation
     92
     93*  Words surrounded by `< >` are to be defined by the person documenting the project
     94  * `<slug>` is the slug name defined on `projects_info.csv` file
     95* The project quickstartfile name is `<slug>_quickstart.rst` for example `udig_quickstart.rst`
     96* Words surrounded by `@ @` are variables
     97* Words surrounded by `| |` are Sphinx variables
     98
     99||= Variable =||= Example =||= Action =||
     100|| @LOGO_<slug>@ || `@LOGO_udig@` || Gets the logo image of the project  if it exists ||
     101|| @OSGEO_KIND_<slug>@ || `@OSGEO_KIND_udig@` || Gets the logo of the kind of project within OSGeo as defined into  `projects_info.csv`||
     102|| @NAME_<slug>@ || `@NAME_udig@` || Gets the name of the project as defined into `projects_info.csv` ||
     103|| @QUICKSTART_<slug>@ || `@QUICKSTART_udig@` || Will generate a link to the quickstart if defined into `projects_info.csv`  ||
     104|| @SCREENSHOT_<slug>@ || `@SCREENSHOT_udig@` || Places the screenshot to a given standard size ||
     105|| |version-<slug>| || `|version-udig|` || Project's version defined into `projects_info.csv`
    125106
    126107
    127 
    128 @LOGO_<slug>@
    129 @OSGEO_KIND_<slug>@
    130 
    131 ********************************************************************************
    132 @NAME_<slug>@ Quickstart
    133 ********************************************************************************
     108Most 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 ]
    134109
    135110
    136 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    137 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
    138 
    139 
    140 .. contents:: Contents
    141    :local:
    142 
    143  
    144 Start application name
    145 ======================
    146 
    147 From the menu, choose :menuselection:`Geospatial --> Desktop GIS --> uDig`. The application opens.
    148 
    149 Porttitor eget dolor morbi non arcu risus quis varius quam.
    150 
    151    .. image:: /images/projects/<slug>/image_name.png
    152    :scale: 70 %
    153 
    154 
    155 Excepteur sint
    156 ==============
    157 
    158 Porttitor eget dolor morbi non arcu risus quis varius quam.
    159 
    160 #. Nisi vitae suscipit tellus mauris a diam maecenas sed.
    161 #. Vestibulum lectus mauris ultrices eros in cursus. Pellentesque habitant morbi tristique senectus et.
    162 #. Nisi quis eleifend quam adipiscing vitae proin sagittis nisl. Ut venenatis tellus in metus vulputate eu scelerisque felis imperdiet.
    163 
    164    .. image:: /images/projects/<slug>/image_name.png
    165    :scale: 70 %
    166 
    167 #. Turpis in eu mi bibendum neque egestas congue quisque egestas.
    168 
    169 
    170 Sit amet purus gravida
    171 ======================
    172 
    173 Et egestas quis ipsum suspendisse ultrices.
    174 
    175 #. Eu sem integer vitae justo. Enim lobortis scelerisque fermentum dui faucibus in ornare. Est ullamcorper eget nulla facilisi etiam dignissim.
    176 #. Nulla posuere sollicitudin aliquam ultrices sagittis. Ultrices dui sapien eget mi proin sed libero. Tellus id interdum velit laoreet id donec ultrices.
    177 Nunc sed velit dignissim sodales. Elit ut aliquam purus sit amet luctus.
    178   * Tortor dignissim
    179   * convallis aenean
    180   * turpis egestas integer
    181 #. Proin fermentum leo vel orci porta. Fermentum odio eu feugiat pretium nibh. Nunc mi ipsum faucibus vitae aliquet. Ac ut consequat semper viverra. Velit ut tortor pretium viverra suspendisse. Mauris augue neque gravida in.
    182 
    183 Eleifend quam adipiscing vitae proin sagittis. Risus viverra adipiscing at in tellus integer feugiat scelerisque variu
    184 
    185 .. tip:: Eget est lorem ipsum dolor sit amet. Nibh nisl condimentum id venenatis.
    186 
    187 
    188 Things to try
    189 =============
    190 
    191 Here are some additional challenges for you to try:
    192 
    193 * Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    194 * Try Praesent pretium mauris id porta convallis.
    195 
    196 
    197 What next?
    198 ==========
    199 
    200 Here are some other resources to learn more about this application:
    201 
    202 * the tutorial - short description of the tutorial. The link: `link title <http://this/is/the/external_link.html>`__
    203 * Tortor condimentum lacinia quis vel eros donec ac.
    204 * Nunc lobortis mattis aliquam faucibus.
    205 
    206 }}}
    207 
    208 
     111It is a good idea to fill the projects_info.csv file first before writing your quickstart. How to fill `projects_info.csv` is explained here : https://trac.osgeo.org/osgeolive/wiki/How%20to%20configure%20a%20project%20documentation