Contributing to Open Source Documentation

Ian Turton, Astun Technology [email protected]

Summary

• Motivation
• Quick Fixes
• Larger changes
  • Git Workflow
  • Software Installation
  • Sphinx hints

Why?

• Frustration
• Want to help
• New Functionality

How?

• Quickfixes
• Major Updates
  • Contribution agreement
  • git
  • rst

Quickfixes

Found a typo? Simple spelling error? Other simple fix?

Click the "edit" or "edit on github" button, or go directly to https://github.com/geoserver/geoserver/tree/master/doc/en

Navigate to the file and press the edit button:

You can now make a change

When you are finished, "propose the change"

Create the pull request

Watch the Pull Request list

OK, so quick was a slight exaggeration

But not too long

Larger changes

Need to sign contribution agreement (in most cases) - this keeps copyright and licensing straight (and keeps the lawyers off everyone's backs).

It is not really that hard, so please do it.

It is a one off process (per project).

Install Git

• windows - https://git-for-windows.github.io/
• macos - https://sourceforge.net/projects/git-osx-installer/files/
• Linux - sudo apt install git

Set up your git workflow

• Create an account on github (or where ever the project is hosted).
• "Fork" the main repository (make a copy for yourself)
• get a local copy of your repository

git clone [email protected]:ianturton/geoserver.git

Make Your changes

• Use a plain text editor
  • Notepad++
  • TextEdit
  • nano

Build the docs

Uses Python, sphinx and latex

See https://docs.geoserver.org/latest/en/docguide/install.html

Writing Restructured Text

A plain text format, that uses "markup" to tell the "compiler" how to format the text. So it is easy to see changes (just the way we do with program code).

Also makes it easier to produce differently formatted outputs depending on need (HTML, PDF, etc).

See https://docs.geoserver.org/latest/en/docguide/sphinx.html

Check the project documentation to see how to build the docs.

• GeoServer - ant user
• GeoTools - ant full
• GDAL - make html

Look for and fix any errors

Push the changes back

• git status -sb - will show what you have changed
• git checkout -b doc-fix
• git add [path/file(s)]
• git commit -m "message describing your fix"
• git push origin doc-fix

Create a Pull Request

Go to GitHub and follow the prompts.

Questions?