为文档做贡献¶

感谢您对改进 Nexus 文档的关注！本指南将帮助您有效地做出贡献。

快速开始¶

前置条件¶

在为文档做出贡献之前，请确保您具备：

Python 3.8 或更高版本
Sphinx 和所需的扩展
用于版本控制的 Git
A text editor (VS Code, Vim, etc.)

设置环境¶

克隆仓库：

git clone https://github.com/nexus-team/nexus.git
cd nexus

安装文档依赖：

pip install -r docs/sphinx/requirements.txt

在本地构建文档：

cd docs/sphinx
python build_docs.py

查看文档：

在您的网络浏览器中打开 _build/html/index.html。

文档结构¶

文档组织如下：

docs/sphinx/
├── getting_started/     # Installation and quickstart guides
├── user_guide/          # User guides for modules and features
├── platform_guides/     # Platform-specific documentation
├── api/                 # API reference (auto-generated)
├── tutorials/           # Step-by-step tutorials
├── development/         # Development guides
├── reference/           # Reference materials
└── _templates/          # Documentation templates

贡献类型¶

我们欢迎以下类型的文档贡献：

修复错误¶

拼写和语法错误
损坏的链接
不正确的代码示例
过时的信息

Improving Existing Documentation¶

Adding missing details
澄清令人困惑的部分
添加图表和插图
改进代码示例

Adding New Documentation¶

新教程
平台指南
Module documentation
API 文档

Translation¶

Translating documentation to Chinese
Maintaining translation consistency
Updating translations when English docs change

写作指南¶

Style Guide¶

Tone and Voice

Use clear, concise language
使用现在时态
使用主动语态
Be direct and specific

Formatting

Use consistent heading levels
Keep line length under 120 characters
Use code blocks with language specification
Include alt text for images

Terminology

Use consistent terminology throughout:

CMake (not CMake)
Kconfig (not Kconfig)
FreeRTOS (not FreeRTOS)
STM32 (not STM32)
GPIO, UART, SPI, I2C (all caps)

代码示例¶

All code examples should:

Be complete and runnable when possible
Include necessary headers and includes
Use meaningful variable names
Include comments for complex sections
Follow the project's coding standards

Example:

#include "hal/nx_gpio.h"

/* Initialize GPIO for LED */
nx_gpio_config_t led_config = {
    .mode = NX_GPIO_MODE_OUTPUT_PP,
    .pull = NX_GPIO_PULL_NONE,
    .speed = NX_GPIO_SPEED_LOW,
};

nx_gpio_t* led = nx_factory_gpio(NX_GPIO_PORT_A, 5);
led->init(led, &led_config);

/* Turn on LED */
led->write(led, 1);

RST Syntax¶

Headings

Use consistent underline characters:

Level 1 Heading
===============

Level 2 Heading
---------------

Level 3 Heading
~~~~~~~~~~~~~~~

Level 4 Heading
^^^^^^^^^^^^^^^

Code Blocks

Always specify the language:

.. code-block:: c

    int main(void) {
        return 0;
    }

Lists

- Bullet item 1
- Bullet item 2

1. Numbered item 1
2. Numbered item 2

Links

:doc:`../user_guide/hal`  # Internal link
`External Link <https://example.com>`_  # External link

Tables

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Column 1
     - Column 2
   * - Value 1
     - Value 2

Diagrams

.. mermaid::
   :alt: Workflow diagram showing process from start to end

   graph TD
       A[Start] --> B[Process]
       B --> C[End]

Using Templates¶

We provide templates for common documentation types:

Module Documentation¶

cp docs/sphinx/_templates/module_template.rst docs/sphinx/user_guide/my_module.rst

Tutorial Documentation¶

cp docs/sphinx/_templates/tutorial_template.rst docs/sphinx/tutorials/my_tutorial.rst

Platform Guide¶

cp docs/sphinx/_templates/platform_guide_template.rst docs/sphinx/platform_guides/my_platform.rst

See the template files in docs/sphinx/_templates/ for detailed template usage.

Contribution Workflow¶

1. Create a Branch¶

git checkout -b docs/improve-hal-guide

Use descriptive branch names with docs/ prefix.

2. Make Changes¶

Edit the relevant RST files
Add new files if needed
Update the table of contents (index.rst)

3. Build and Test¶

cd docs/sphinx
python build_docs.py

Check for:

Build warnings or errors
损坏的链接
Formatting issues
Code example correctness

4. Run Quality Checks¶

# Check style
python check_style.py

# Check spelling
python check_spelling.py

# Validate code examples
python validate_code_examples.py

5. Commit Changes¶

git add docs/sphinx/user_guide/my_module.rst
git commit -m "docs: improve HAL GPIO documentation

- Add missing configuration examples
- Clarify interrupt handling
- Fix code example errors"

Use conventional commit format:

docs: description for documentation changes
docs(module): description for module-specific changes

6. Push and Create Pull Request¶

git push origin docs/improve-hal-guide

Then create a pull request on GitHub with:

Clear title describing the change
Description of what was changed and why
Reference to any related issues

审查流程¶

What to Expect¶

Automated Checks: CI will run style checks, spell checking, and link validation
Peer Review: Maintainers will review your changes
Feedback: You may receive suggestions for improvements
Approval: Once approved, your changes will be merged

Responding to Feedback¶

处理所有审查评论
Ask questions if something is unclear
Make requested changes promptly
Update your pull request with fixes

Translation Guidelines¶

If you're contributing translations:

工作流¶

Extract translatable strings:

sphinx-build -b gettext . _build/gettext

Update translation files:

sphinx-intl update -p _build/gettext -l zh_CN

Edit .po files in locale/zh_CN/LC_MESSAGES/
Build translated documentation:

sphinx-build -b html -D language=zh_CN . _build/html/zh_CN

Translation Best Practices¶

Maintain consistent terminology
Preserve formatting and markup
Keep technical terms in English when appropriate
Test the translated documentation

Common Issues¶

Build Errors¶

Issue: WARNING: document isn't included in any toctree

Solution: Add the document to an index.rst file:

.. toctree::
   :maxdepth: 2

   my_new_document

Issue: ERROR: Unknown directive type "code-block"

Solution: Ensure proper indentation and blank lines:

.. code-block:: c

   int main(void) {
       return 0;
   }

Link Errors¶

Issue: WARNING: undefined label

Solution: Check that the referenced document exists and is in the toctree.

Style Violations¶

Issue: Heading underline length mismatch

Solution: Ensure underline matches heading length exactly:

My Heading
==========

获取帮助¶

If you need help:

Check existing documentation in docs/sphinx/
Review this contributing guide
Ask questions in pull request comments
Contact maintainers via GitHub issues

资源¶

Thank You!¶

Your contributions help make Nexus better for everyone. We appreciate your time and effort!