Improvement: Integrate RST Formatter for Sphinx Documentation Source Files

[nradakovic]

Background

Our .rst documentation files, used by Sphinx, play a critical role in our project's documentation quality and accessibility. Maintaining consistent formatting across these files is essential for improving readability, reducing errors, and ensuring maintainability. Currently, no standardized formatter is applied, leading to potential inconsistencies and increased review overhead.

Objectives

• Research and integrate a reliable RST formatter that supports .rst files used by Sphinx.
• Ensure compatibility between the formatter and existing RST linting tools (see Improvement: Integrate RST linting for documentation source files #124 ).
• Integrate the selected tool as part of Bazel build system.
• Provide developers with clear instructions to use the formatter locally.

Acceptance Criteria

• A suitable RST formatter is identified and integrated into the project.
• Compatibility between the formatter and linting tools is verified.
• The tool is integrated as part of Bazel build system.
• Documentation includes guidelines for using the formatter locally and as part of the contribution process.
• Optional: The tool is invoked over bundle target //:format.fix

Proposed Steps

• Research: Evaluate available RST formatters (e.g., docformatter, rstfmt) and select the most suitable one for Sphinx-based projects.
• Compatibility Check: Test the selected formatter with existing linting tools to avoid conflicts or redundant errors.
• Integration: Create Bazel custom rule which will invoke RST Formatter with nessesary arguments.
• Documentation: Write instructions for developers to use the formatter locally, including installation, configuration, and usage examples.
• Validation: Perform tests on existing .rst files to ensure the formatter produces desirable and consistent results.

Resources

• docformatter GitHub Repository
• rstfmt GitHub Repository
• rstcheck Documentation
• Sphinx Documentation

Impact

Integrating an RST formatter will standardize documentation formatting, improving readability and reducing manual effort during reviews. Automated checks in the CI pipeline will ensure consistent quality, fostering a smoother contribution process and enhancing overall documentation standards.

NOTE: This ticket is part (subtask) of #36