Contributing

There are several topics in Source.Python you can contribute to and we appreciate every contribution! To contribute to Source.Python, please use Github’s pull request functionality. You can read more about pull request on the Github help page.

When creating a pull request, please always provide a reason why you made that change. We will then review, discuss and merge or close it.

If you successfully contributed to Source.Python we will gladly add you to our credits page (if you want).

Contributing to the source code

If you want to contribute to the source code you can simply create a pull request. But before creating a new pull request, please consider these two points.

  1. Test the changes you have made.
  2. Try to roughly meet our coding convention.

Contributing to the wiki

Contributing to this wiki will also be done via pull requests. We are using Sphinx to create the wiki. Therefore, you can find rst-files in Source.Python’s documentation directory (../addons/source-python/docs/source-python/source). rst-files in that directory are usually simple wiki pages like this one.

The source code is documented in the modules sub-directory. It’s mostly auto-documented, so these files only contain a few directives. E.g.

bitbuffers module
==================

.. automodule:: bitbuffers
    :members:
    :undoc-members:
    :show-inheritance:

The automodule directive tells Sphinx to parse the bitbuffers module and look for Sphinx directives in the doc strings of the Python objects in that module (e.g. functions and classes). However, in some cases you have to manually document specific things in a module. In that case you can simply extend or replace the rst-file of the module you want to edit.

Before creating a pull request you should also test if the HTML output of your change is correct and looks good. To do so you can build an offline copy of the wiki. Building an offline copy is very simple.

  1. Install a game server.
  2. Install Source.Python.
  3. Run sp docs build source-python.
  4. Open ../addons/source-python/docs/source-python/build/index.html and review your changes.

Warning

If you have made a change to the source code documentation directly in the source code, you have to restart your server.

Note

Always restarting and typing the long build command can get very annoying. But luckily you can create server command aliases. Just add alias b sp docs build source-python to your autoexec.cfg. Then you only need to enter b in your server console to build the offline wiki.

If we have merged your pull request our buildbot will be triggered and a new build will be created. As soon as the new build has been finished it’s used to build a new wiki that gets published automatically. The whole process usually takes 20-30 minutes.