Documentation guidelines

This page describes the rules to follow if you want to contribute to Pandemonium Engine by writing or reviewing documentation, or by translating existing documentation. Also, have a look at README of the pandemonium-docs GitHub repository ( https://github.com/Relintai/pandemonium_engine-docs ) and the docs front page ( https://docs.pandemoniumengine.org ) on what steps to follow and how to contact the docs team.

How to contribute

Creating or modifying documentation pages is mainly done via the pandemonium-docs GitHub repository ( https://github.com/Relintai/pandemonium_engine-docs ). The HTML (or PDF and EPUB) documentation is generated from the .rst files (reStructuredText markup language) in that repository. Modifying those pages in a pull request and getting it merged will trigger a rebuild of the online documentation.

See also: For details on Git usage and the pull request workflow, please refer to the doc_pr_workflow page. Most of what it describes regarding the main pandemoniumengine/pandemonium repository is also valid for the docs repository.

Warning: The class reference's source files are in the Pandemonium engine repository ( https://github.com/Relintai/pandemonium_engine ). We generate the Pandemonium API ( toc-class-ref ) section of this documentation from them. If you want to update the description of a class, its methods, or properties, read doc_updating_the_class_reference.

Warning: If you want to edit the API reference, please note that it should not be done in the pandemonium-docs repository. Instead, you should edit the doc/classes/* XML files of Pandemonium's main repository. These files are then later used to generate the in-editor documentation as well as the API reference of the online docs. Read more here: doc_updating_the_class_reference.

The 'Edit on GitHub' link

If you're reading documentation on docs.pandemoniumengine.org ( https://docs.pandemoniumengine.org ), you'll see an Edit on GitHub hyperlink at the top right of the page. Once you've created a GitHub account, you can propose changes to a page you're reading as follows:

Click the Edit on GitHub button.
On the GitHub page you're taken to, click the pencil icon in the top-right corner near the Raw, Blame and History buttons. It has the tooltip "Edit the file in a fork of this project".
Complete all the edits you want to make for that page.
Summarize the changes you made in the form at the bottom of the page and click the button labelled Propose file change when done.
On the following screens, click the Create pull request button until you see a message like Username wants to merge 1 commit into pandemoniumengine:master from Username:patch-6.
A reviewer will evaluate your changes and incorporate them into the docs if they're acceptable. You might also be asked to make modifications to your changes before they're included.

What makes good documentation?

Documentation should be well written in plain English, using well-formed sentences and various levels of sections and subsections. It should be clear and objective. Also, have a look at the doc_docs_writing_guidelines.

We differentiate tutorial pages from other documentation pages by these definitions:

Tutorial: a page aiming at explaining how to use one or more concepts in the editor or scripts in order to achieve a specific goal with a learning purpose (e.g. "Making a simple 2d Pong game", "Applying forces to an object").
Documentation: a page describing precisely one and only one concept at a time, if possible exhaustively (e.g. the list of methods of the Sprite class, or an overview of the input management in Pandemonium).

You are free to write the kind of documentation you wish, as long as you respect the following rules (and the ones on the repo).

Titles

Always begin pages with their title and a Sphinx reference name:

    Insert your title here
    ======================

The reference allows linking to this page using the format, e.g.doc_insert_your_title_here``` would link to the above example page (note the lack of leading underscore in the reference).

Also, avoid American CamelCase titles: title's first word should begin with a capitalized letter, and every following word should not. Thus, this is a good example:

Insert your title here

And this is a bad example:

Insert Your Title Here

Only project, people and node class names should have capitalized first letter.

Translating existing pages

You can help to translate the official Pandemonium documentation on our Hosted Weblate ( https://hosted.weblate.org/engage/pandemonium-engine/ ).

:alt: Translation state :align: center :target: https://hosted.weblate.org/engage/pandemonium-engine/?utm_source=widget :width: 287 :height: 66

There also is the official Pandemonium i18n repository ( https://github.com/Relintai/pandemonium_engine-docs-l10n ) where you can see when the data was last synchronized.

License

This documentation and every page it contains is published under the terms of the Creative Commons Attribution 3.0 license (CC-BY-3.0) ( https://tldrlegal.com/license/creative-commons-attribution-(cc) ), with attribution to "Péter Magyar and the Pandemonium community, and Juan Linietsky, Ariel Manzur and the Godot community".

By contributing to the documentation on the GitHub repository, you agree that your changes are distributed under this license.

5.8 KiB Raw Blame History