This addresses the following topics:
By submitting suggestions, corrections, or content to this repository you hereby agree to the following terms and conditions.
Any content submitted to these forums will be reviewed to check for accuracy, usability, and direction for the Xenko project. Although all submissions will be considered fairly, Xenko makes no guarantees to accept and or use any submitted content.
If submitted content is accepted for addition or usage in the documentation, the contributor will be asked to agree and electronically sign the Contributor License Agreement. Among other things, it stipulates that the contributor keeps the ownership on its contribution but gives a perpetual license to Xenko to re-publish, edit and remove the content at its leisure.
Note that content containing any offensive material or actions of spam submission or the like will be immediately rejected. Any users who make repeat or continuous actions of the above in either submissions or Git-hub forums will be banned from access to the either process.
After submitting please remain patient while your content is reviewed whereas the process may take some time. All submissions will be answered based on the Xenko team priority.
To facilitate discussions and reviews of new content, please follow the following workflow when you contribute:
- Start by creating an issue on GitHub describing the changes or the additions you plan to make
- Wait for the review and the green-light from the Xenko team
- Assign the issue to you to show others contributors that you are currently dealing with the issue
- Create a branch containing (at least) the name of the issue
- Write your article and add media files in the adequate folders
- Make a pull request and wait for acceptance and integration of your changes
Remarks:
- For minor changes (typos, code update, etc.) you can directly create a pull request, no need to create an issue.
- Alternatively if you don't have specific changes in mind but just want to contribute, you can also start from an existing unassigned issue.
- If you stop dealing with an issue, mark it as unassigned to let the other contributors know that this issue is available.
To learn how to use GitHub and what is an issue, a branch and a pull request, have a look at the GitHub Guides.
Xenko currently uses DocFX to generate its documentation.
All the documentation content is formatted using the MarkDown format.
To locally edit, build and test the documentation:
- Checkout this repository on your PC
- Make your changes to the adequate MarkDown files
- If you added a new MarkDown file, reference it inside the toc.md files to include it in the build
- Double-click on the build.bat batch file to build the doc
- Double-click on the run_local_website.bat batch file. It opens the local version of the doc in your browser
- Every time you want to see your latest changes, run again build.bat and refresh your browser by pressing F5
Remarks:
- If you want to locally test links to the API documentation, you need to checkout the Xenko Repository next to the documentation (or adjust the '../xenko' path in the docfx.json file). Note that the build time is much more consequent when building both Manual and API documentation (you can use build_manual_only.bat script to build only the manual in that case).
- For more details about the MarkDown format, see GitHub MarkDown Guide or this Tutorial.
- For more details about DocFX, see DocFX Getting Started Page
Articles should be organized in folders. Media and code files should be stored in folders named media and code and placed next to the article using them.
For more details about the files structure, read the Guidelines.
In order to create an homogeneous documentation and provide the best experience to all Xenko users, we would like you to follow the following Guidelines when you write your articles.
Thank you for you contribution!