Quick Reference Card

Essential commands and references for Nexus documentation.

Build Commands

Build all languages:

python build_docs.py

Build specific language:

python build_docs.py --lang en      # English
python build_docs.py --lang zh_CN   # Chinese

Clean and rebuild:

python build_docs.py --clean

Build and serve:

python build_docs.py --serve
# Visit http://localhost:8000

Full build (with Doxygen):

python build_docs.py --doxygen
# or
make full

Translation Commands

Update translation files:

python build_docs.py --update-po

Auto-translate common terms:

python translate_helper.py zh_CN --auto-translate

Show translation statistics:

python translate_helper.py zh_CN --stats

Validate translations:

python translate_helper.py zh_CN --validate

Initialize new language:

python build_docs.py --init-po ja  # Japanese

Makefile Shortcuts

make help          # Show all targets
make html-all      # Build all languages
make html-zh_CN    # Build Chinese only
make serve         # Build and serve
make full          # Clean + Doxygen + Build
make stats         # Translation statistics
make validate      # Validate translations
make linkcheck     # Check for broken links

reStructuredText Syntax

Headings:

Main Title
==========

Section
-------

Subsection
~~~~~~~~~~

Text formatting:

**bold text**
*italic text*
``inline code``

Code blocks:

.. 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:`path/to/document`           # Internal document
:ref:`label-name`                 # Internal reference
`External Link <https://...>`_    # External link

Admonitions:

.. note::

   Important information

.. warning::

   Critical warning

.. tip::

   Helpful suggestion

Tables:

+--------+--------+
| Header | Header |
+========+========+
| Cell   | Cell   |
+--------+--------+

Images:

.. image:: path/to/image.png
   :alt: Alternative text
   :width: 400px

Mermaid diagrams:

.. mermaid::

   graph LR
       A --> B
       B --> C

Common File Locations

Documentation source:

docs/sphinx/
├── index.rst              # Main entry point
├── getting_started/       # Getting started guides
├── user_guide/           # User documentation
├── tutorials/            # Tutorials
├── api/                  # API reference
└── development/          # Development guides

Build output:

docs/sphinx/_build/html/
├── index.html            # Language selector
├── en/                   # English docs
└── zh_CN/                # Chinese docs

Translation files:

docs/sphinx/locale/
└── zh_CN/
    └── LC_MESSAGES/
        ├── index.po
        ├── getting_started/
        ├── user_guide/
        └── ...

Configuration:

docs/sphinx/
├── conf.py               # Sphinx configuration
├── build_docs.py         # Build script
├── translate_helper.py   # Translation tool
└── Makefile              # Make targets

Documentation Conventions

File naming:

  • Use lowercase with underscores: my_module.rst

  • Be descriptive: gpio_control.rst not gpio.rst

Cross-references:

  • Use :doc: for documents: :doc:`user_guide/hal`

  • Use :ref: for sections: :ref:`gpio-config`

Code examples:

  • Always specify language: .. code-block:: c

  • Include comments for clarity

  • Keep examples concise and focused

Admonitions:

  • .. note:: - Additional information

  • .. warning:: - Important warnings

  • .. tip:: - Helpful suggestions

  • .. important:: - Critical information

Quick Troubleshooting

Build fails:

# Check dependencies
pip install -r requirements.txt

# Clean and rebuild
python build_docs.py --clean

Translation not showing:

# Update .po files
python build_docs.py --update-po

# Rebuild specific language
python build_docs.py --lang zh_CN

Broken links:

# Check all links
make linkcheck

# View report
cat _build/linkcheck/output.txt

Doxygen errors:

# Run Doxygen manually
cd ../..
doxygen Doxyfile

# Check for errors in output

Common Tasks Checklist

Adding new documentation:

☐ Create .rst file in appropriate directory ☐ Add to toctree in index file ☐ Write content following conventions ☐ Build and verify locally ☐ Update translations if needed ☐ Submit pull request

Updating existing documentation:

☐ Edit .rst file ☐ Update cross-references if needed ☐ Build and verify changes ☐ Update translations ☐ Check for broken links ☐ Submit pull request

Adding translation:

☐ Run python build_docs.py --update-po ☐ Edit .po files in locale/LANG/LC_MESSAGES/ ☐ Run python translate_helper.py LANG --validate ☐ Build translated docs ☐ Verify in browser ☐ Submit pull request

Release documentation:

☐ Update version in conf.py ☐ Update changelog ☐ Build all languages ☐ Run linkcheck ☐ Validate all translations ☐ Tag release ☐ Deploy to hosting

Keyboard Shortcuts (VS Code)

Editing:

  • Ctrl+Space - Autocomplete

  • Ctrl+/ - Toggle comment

  • Ctrl+Shift+P - Command palette

Navigation:

  • Ctrl+P - Quick file open

  • Ctrl+Shift+F - Search in files

  • F12 - Go to definition

Preview:

  • Install "reStructuredText" extension

  • Ctrl+Shift+R - Preview RST file

Tips and Best Practices

Writing:

  • Keep paragraphs short and focused

  • Use active voice

  • Include code examples

  • Add cross-references liberally

Translation:

  • Translate content, not code

  • Preserve RST markup

  • Use consistent terminology

  • Validate before committing

Building:

  • Build frequently during development

  • Use --serve for live preview

  • Check warnings in build output

  • Validate links regularly

Maintenance:

  • Update translations when content changes

  • Keep dependencies up to date

  • Review and update examples

  • Monitor build performance

Need Help?

---

Last updated: 2026-01-25 Version: 2.0