Docs Contributing Guide¶

Thank you for your interest in contributing to the Rigs of Rods project documentation. This guide will walk you through the process of setting up your environment, making changes, and submitting your contributions. The documentation is built using MkDocs with the Material for MkDocs theme and deployed directly to GitHub Pages.

Prerequisites¶

Before you start, ensure you have the following installed:

• git: To clone the repository and push your changes.
• Python 3.9+: MkDocs is a Python-based tool.
• pip: Python package manager, which is usually bundled with Python itself.

You can alternatively use something like GitHub Desktop in place of using git itself.

Setting Up Your Environment¶

1. Fork the Repository:
   • Fork the repository on GitHub to your own personal GitHub account.
2. Clone your Fork:

   $ git clone https://github.com/<YOUR_USERNAME>/docs.rigsofrods.org ror-docs
   $ cd ror-docs
   

3. Set Up a Virtual Environment (optional, but recommended):

   $ python -m venv venv
   $ source venv/bin/activate # On Windows, use `venv/Scripts/activate`
   

4. Install Dependencies:

   pip install -r requirements.txt
   

Making Changes¶

1. Create a New Branch:

   $ git checkout -b my-cool-change
   

2. Make Your Changes:
   • The documentation is written in Markdown (.md) and located in the source/ directory.
3. Update the Navigation:
   • Open mkdocs.yml at the root directory.
   • Add the new page to the nav: section, for example:

     nav:
         - My new page: tools-tutorials/my-new-page.md
     

Previewing Your Changes¶

1. Run the MkDocs Development Server:

   $ mkdocs serve
   

   • This will start a local server at http://127.0.0.1:8000/ where you can preview your changes in real-time.
2. Check for Errors:
   • Ensure there are no build errors or broken links. MkDocs will display errors in the terminal if any exist.

Submitting Your Contributions¶

1. Commit Your Changes:

   $ git add .
   $ git commit -m "Your descriptive commit message"
   

2. Push to Your Fork:

   git push
   

3. Create a Pull Request (PR):
   • Go to your fork on GitHub and click "Compare & Pull Request."
   • Write a clear title and description for your PR, explaining the changes you made.
   • Submit the PR and wait for feedback from the maintainers.

Style Guide¶

To maintain consistency across the documentation, please follow these guidelines:

1. Markdown Formatting:
   • Use headings (#, ##, ###) to structure your content.
   • Use fenced code blocks for code snippets:

     ```python
     print("Hello world")
     

2. Language and Tone
   • Use clear, concise, and friendly language.
   • Write in an active voice whenever possible.
3. Admonitions:
   • Use Material for MkDocs admonitions to highlight important information:

     !!! note
         This is a note.
     

4. Links:
   • Use relative links for internal documentation pages.
   • Use descriptive anchor text for external links.

Code of Conduct¶

By contributing, you agree to follow our Contributor Code of Conduct. Please be respectful and inclusive in all interactions.

Finally, thank you for contributing to the Rigs of Rods project and community! Your efforts will help make the project better for everyone.