wiki:How to configure a project documentation

Version 13 (modified by flicstar, 5 years ago) ( diff )

Added link to how to document quickstart file page

How to update / add a project in the documentation

Since documentation is built automatically, projects data are stored in project_info.csv file. It is the main point of entry of the docs.

It can be found here: https://github.com/OSGeo/OSGeoLive-doc/blob/master/projects_info.csv

To add a new project, you have to add a new line in this file. To update a project informations, just modify the corresponding line. Then commit and push your changes and make a pull request to the OSGeoLive repository.

project_info.csv organization

The file is organized with 12 columns/fields separated by the pipe | symbol:

# document? | slug |version| Quickstart? |Overview?|Section| last | One Liner| OpenHub name |URL|kind|name

The 12 fields are described below.

Several categories have been made with comments to help organize the projects. Please add your project in the corresponding one:

  • Desktop GIS : General GIS viewing, editing and analysis in the browser
  • Browser Facing GIS: General GIS viewing, editing and analysis in the browser
  • Web Services: Publishing spatial data to the internet
  • Data Stores: Storing spatial data
  • Navigation and Maps
  • Spatial Tools: Specific analysis tools
  • Domain Specific GIS: Applications targeted at a specific domain
  • Data: Spatial data sets
  • Geospatial Libraries
  • RETIRED: projects that have been retired for some reason but can be reactivated

Fields description

Each field have a purpose in the doc building and should be fill carefully.

  • document?
  • page/project name (slug)
  • version
  • Quickstart?
  • Overview?
  • Classification
  • last
  • One Liner
  • OpenHub name
  • URL
  • kind
  • name

document?

Add Y if the project documentation should be build or not reserved to OSGeoLive members

If the project have been retired, please change it to N and move it to retired section.

slug

Page name used to construct logo-<slug>.png <slug>_screenshot.png <slug>_overview.rst etc. Page name can contains dashes, underscore, numbers or capital letters but no spaces.

Examples:

  • pgRouting is the real name of the project but the page name is pgrouting
  • User-friendly Desktop Internet GIS is the real name of the project but udig is the page name
  • it gives: udig_overview.rst udig_quickstart.rst logo-udig.png udig-screensot.png

version

Version of the project

Examples:

  • 2.14.14 for QGIS 2.14.14
  • 4.3.0a for 4.3.0 alpha release of Spatialite

Quickstart?

Is there a quickstart ? Add Y if the documentation should build a quickstart page for this project, N if it doesn't.

Overview?

Is there an overview ? Add Y if the documentation should build an overviewpage for this project, N if it doesn't.

Classification

General category where your project fit in. Please choose in the ones provided below. If your project needs a special category, please contact the OSGeoLive team so we can add it in our building process. Otherwise, the pages won't be built.

Desktop GIS | Browser Facing GIS | Web Services | Data Stores | Navigation and Maps | Spatial Tools | Domain Specific GIS | Data | Geospatial Libraries

last

Used only for deprecated / removed projects and has the last version of OSGeoLive where it was available

One Liner

One line description that goes after the quickstart link in the Overview page

OpenHub name

When the project is registered onto OpenHub

  • Please provide the OpenHub name

For example: This is the link to OpenHub for pgRouting: https://www.openhub.net/p/pgrouting

Then the OpenHub name is pgrouting

URL

Please insert here the complete URL of your project

kind

How are you related to OSGeo ? Are you community ? In incubation or an OSGeo project ? If yes, the corresponding logo will be added to your project pages under the project logo.

Parameters:

  • OSGeo_community
  • OSGeo_project
  • OSGeo_incubation
  • blank

name

Complete name of the project respecting the case (unlike slug).

For example pgRouting (slug is pgrouting)

General file structure

Overviews and quickstarts

Each project has to have an Overview and a Quickstart. You can find more information on the dedicated pages:

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.

Locally, on your computer, it should be like this: doc/images/projects/<slug>/

Please note that images have to be in the png format.

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

For example, for gvSIG, the project slug is: gvsig so the logo is doc/images/projects/gvsig/logo_gvsig.png

Update project screenshot

Like logos, project screenshots for the overview page are stock in the images folder following this path:

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. That way it will be find easily during the creation of the documentation.

It should be like this: doc/images/projects/<slug>/<slug>_screenshot.png

For example, for QGIS, the project slug is: qgis so the logo is doc/images/projects/qgis/qgis_screenshot.png

Note: See TracWiki for help on using the wiki.