TrustedUser, Bureaucrats, Administrators
442
edits
Difference between revisions of "Developer Central"
Jump to navigation
Jump to search
Adds contribution guide for technical writers
(Adds contribution guide for technical writers) |
|||
| Line 114: | Line 114: | ||
If you want to regenerate from the data spreadsheet: | If you want to regenerate from the data spreadsheet: | ||
* composer update-data | * composer update-data | ||
== Contribution guide for technical writers == | |||
The user documentation is located at [https://docs.scummvm.org/en/latest/ docs.scummvm.org]. It is written in reStructuredText or markdown, built using Sphinx, and deployed by Read the Docs. The recommonmark extension enables parsing of markdown files. The [https://sphinx-panels.readthedocs.io/en/latest/ sphinx-panels] extension uses custom rST directives to provide Bootstrap functionality. All documentation is written to conform to the Google developer documentation [https://developers.google.com/style style guide]. | |||
=== For small changes === | |||
For small changes to existing documentation, such as fixing spelling, grammar, or correcting a mistake: | |||
The easiest way to make a change is to use the '''Edit this page on GitHub''' link on the applicable page to edit documentation online, on GitHub. Bear in mind that you won’t be able to upload images while working in this way. Once you are happy with your changes, create a pull request (PR). The ScummVM team will review the pull request, and if there are no issues, it will be merged into the existing code. | |||
=== For large changes === | |||
For larger changes, such as documenting a new feature, documenting a new (or existing) port, or writing a guide: | |||
==== Set up your environment ==== | |||
1. Install Python3. | |||
* Linux: Comes with Python3 installed | |||
* [https://www.digitalocean.com/community/tutorials/how-to-install-python-3-and-set-up-a-local-programming-environment-on-macos macOS] | |||
* [https://phoenixnap.com/kb/how-to-install-python-3-windows Windows]. | |||
2. Install pip3. | |||
* Linux: Install pip3 from the software repository. For a Debian-based distro, use <code>sudo apt install python3-pip</code> | |||
* Windows: Pip3 is installed when you install Python3. | |||
* macOS: Pip3 is installed if you install Python3 with Homebrew. | |||
3. Use pip3 to install [https://www.sphinx-doc.org/en/master/usage/installation.html Sphinx], [https://sphinx-panels.readthedocs.io/en/latest/#installation sphinx-panels] and [https://www.sphinx-doc.org/en/master/usage/markdown.html recommonmark]. | |||
4. [https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/set-up-git Install Git], if you don’t have it already. | |||
5. [https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo Fork and clone] the [https://github.com/scummvm/scummvm scummvm repository]. | |||
6. [https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository Create and checkout] a new branch. | |||
==== Create and edit documentation ==== | |||
Documentation files are found in <code>scummvm/doc/docportal/ </code>. | |||
Images, screenshots and GIFs are found in <code>scummvm/doc/docportal/images/ </code>. | |||
There are many options for editing and creating documents. A particularly good one is [https://code.visualstudio.com VS Code], which features extensions to help you write in reStructuredText/markdown, as well as Git integration. | |||
Here is a [https://rest-sphinx-memo.readthedocs.io/en/latest/intro.html handy guide] to reStructuredText, as it is used by Sphinx. | |||
If you are creating a new Platform or Settings page, use the template provided in the docportal directory: <code>platform_template.rst</code> or <code>settings_template.rst</code>. This is to ensure our documentation remains consistent and predictable for the end user. | |||
==== Preview your documentation ==== | |||
To build a preview of the documentation, open a new Terminal window, and change your working directory until you are in the <code>docportal</code> directory. Use the <code>make html</code> command. The output HTML files are in the <code>scummvm/doc/docportal/_build/html/</code> directory. Open the <code>index.html</code> file in a browser to view the index page of the site. | |||
Note: | |||
Do not commit the <code>_build</code> folder to your branch. The documentation is built by Read the Docs before deployment, so the local build is not required. | |||
==== Commit your work ==== | |||
Follow the ScummVM [[Commit Guidelines | Commit Guidelines]] when you [https://github.com/git-guides/git-commit make a commit]. | |||
==== Create a Pull Request ==== | |||
For documentation related to the CURRENT release, create a pull request against the branch for the current version. For example, to make a change or add documentation applicable to ScummVM version 2.2.0, open a pull request against <code>branch-2-2-0</code>. For documentation related to the NEXT release, open a pull request against the <code>master</code> branch. | |||
== Projects, plans, things to do == | == Projects, plans, things to do == | ||