Each project in OSGeoLive has to have a Project Overview, a Quickstart, and a section within our Lightning Presentation. You can find more information on the dedicated wiki pages about Overviews and Quickstarts. :
- https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20overview%20file
- https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20quickstart%20file
The information for the presentation is extracted from projects_info.csv
Build documentation can be found at:
- Stable Release: https://live.osgeo.org
- On OSGeoLive disc and VM:
http://localhost/which is stored in/var/wwwand opened want you launch Firefox - Stable Release: https://live.osgeo.org
- Nightly Build: http://adhoc.osgeo.osuosl.org/livedvd/docs/en/index.html TBD: As of May 2019, this hasn't been updated for a while, and points to an old release.
- Build process: https://github.com/OSGeo/OSGeoLive-doc/blob/master/README.rst
The following sections describe components required by OSGeoLive docs, and how to create/update them:
- How to configure a project documentation by filling
projects_info.csv - How to document the overview file
- How to document the quickstart file
- How to update Glossary terms
Images
Images are stocked in a specific folder: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects
To create a new project, create a new folder here with slug of your project. As the screenshot and the logo image will be use automatically to build the overview page, be careful with their name.
Please use a slug that you can create following directions in How to configure a project documentation.
Locally, on your computer, it should be like this: doc/images/projects/<slug>/
The image folder of the GDAL project can be used as a reference.
Please note that images have to be in the png format.
The following section details specific indications about those images. The logo and the screenshot are used in several parts (Overview, Quickstart, Presentation) that are automatically build. These instructions must be followed carefully to unsure that the documentation is correctly build.
Logo
The project's logo is used in the headers of documentation (like Project Overviews, QuickStarts, the presentation etc, and as icons on the OSGeoLive desktop.
Header logo:
- Stored here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects/<project>/
- Filename should be "logo-<project>.png"
- Should have a transparent background (not white)
- Stored in size 125x125 pixels (for use in Project Overview and QuickStarts)
- For PNGs run a program like pngcrush or optipng to reduce the size of the image without degrading quality. For example:
optipng -o5 image.png
For example, for gvSIG, the project slug is: gvsig so the logo is doc/images/projects/gvsig/logo_gvsig.png
- Preferably also available as SVG, stored as "logo-<project>.svg"
Desktop logo
Old docs suggested they might be:
- A 32x32-pixel XPM icon for use by the Debian menus
- A 48x48-pixel PNG icon for use by freedesktop.org menus
Update project logo
Project logos are stock in the images folder of the OSGeolive-doc folder following this path: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects and are stocked in the project folder.
So if you want to change/update your project logo, just change the file there and that's it. Please call it logo_<your-project-slug>.png so the program can find it.
It should be like this: doc/images/projects/<slug>/logo_<slug>.png
Screenshot
Project Overviews include an image, which is usually a screenshot, or collage of screenshots.
Quickstarts include screenshots for each significant step.
How to name and store your screenshot
- Images must be stored here, in a dedicated folder, https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects
- For the automated process of building the documentation, we need you to call your screenshot image like this:
<your-project-slug>_screenshot.png. - for the screenshot present in the overview, it should be like this stored:
doc/images/projects/<slug>/<slug>_screenshot.png
Note that the main screenshot used for the overview needs to be called <your-project-slug>_screenshot.png but other screenshots can be named as you want but must keep the <project-slug>_ prefix.
Screenshots size and format
- Screenshots should be taken from a 1024x768 display and should be created in PNG format.
- Screenshots can be taken using Shutter (on linux) or Greenshot (on windows).
- For Quickstarts, consider marking up the image to explain the current steps. Eg: Add circled numbers: 1, 2, 3 or draw an oval around buttons being described. This is very easy to do using the "Edit" tab in the Shutter program, which provides these drawing icons to add. Tutorials augmented with detailed and pertinent images make it easy for the reader to follow what is going on. Extra time spent on an image pays off big in comprehension (you need more than just a course screen dump). Lines, numbering, highlights, boxes and annotations all help direct a user's focus to those areas which are important.
- Screenshots with large areas of constant color (menus, etc.) should be in PNG format, screenshots containing large areas of imagery (satellite images, shaded relief DEMs, etc.) should be in JPEG format.
- For PNGs run a program like pngcrush to reduce the size of the image without degrading quality.
