mirror of
https://github.com/Relintai/pandemonium_engine_docs.git
synced 2025-01-08 15:09:50 +01:00
143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
|
|
|
|
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:
|
|
|
|
1. Click the **Edit on GitHub** button.
|
|
|
|
2. 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".
|
|
|
|
3. Complete all the edits you want to make for that page.
|
|
|
|
4. Summarize the changes you made in the form at the bottom of the page and
|
|
click the button labelled **Propose file change** when done.
|
|
|
|
5. 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*.
|
|
|
|
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.
|