Skip to content

Contributing to YADT

How to contribute to YADT

About Language

  • Issues can be in Chinese or English
  • PRs are limited to English
  • All documents are provided in English only

Did you find a bug?

  • Ensure the bug was not already reported by searching on GitHub under Issues.

Please pay special attention to:

  1. Known compatibility issues with pdf2zh - see #20 for details

  2. Reported edge cases and limitations from downstream applications - see #23 for discussion

  3. If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible.

If you wish to request changes or new features

  • Suggest your change in the Issues section.

If you wish to add more translators

  • This project is not intended for direct end-user use, and the supported translators are mainly for debugging purposes. Unless it clearly helps with development and debugging, PRs for directly adding translators will not be accepted.
  • You can directly use PDFMathTranslate to get support for more translators.

If you wish to contribute to YADT

Tip

If you have any questions about the source code or related matters, please contact the maintainer at aw@funstory.ai .

You can also raise questions in Issues.

You can contact the maintainers in the pdf2zh discussion group.

We welcome pull requests and will review your contributions.

  1. Fork this repository and clone it locally.
  2. Use doc/deploy.sh to set up the development environment.
  3. Create a new branch and make code changes on that branch. git checkout -b feature/<feature-name>

  4. Perform development and ensure the code meets the requirements.

  5. Commit your changes to your new branch.

git add .

git commit -m "<semantic commit message>"

  1. Push to your repository: git push origin feature/<feature-name>.

  2. Create a PR on GitHub and provide a detailed description.

  3. Ensure all automated checks pass.

Basic Requirements

Workflow

  1. Please create a fork on the main branch and develop on the forked branch.

  2. When submitting a Pull Request (PR), please provide detailed descriptions of the changes.

  3. If the PR fails automated checks (showing checks failed and red cross marks), please review the corresponding details and modify the submission to ensure the new PR passes automated checks.

  4. Development and Testing

  5. Use the uv run yadt command for development and testing.

  6. When you need print log, please use log.debug() to print info. DO NOT USE print()

  7. Code formatting

  8. Dependency Updates

  9. If new dependencies are introduced, please update the dependency list in pyproject.toml accordingly.

  10. It is recommended to use the uv add command for adding dependencies.

  11. Documentation Updates

  12. If new command-line options are added, please update the command-line options list in README.md accordingly.

  13. Commit Messages

  14. Use Conventional Commits, for example: feat(translator): add openai.

  15. Coding Style

  16. Please ensure submitted code follows basic coding style guidelines.

  17. Use pep8-naming.
  18. Comments should be in English.
  19. Follow these specific Python coding style guidelines:

a. Naming Conventions:

  • Class names should use CapWords (PascalCase): class TranslatorConfig
  • Function and variable names should use snake_case: def process_text(), word_count = 0
  • Constants should be UPPER_CASE: MAX_RETRY_COUNT = 3
  • Private attributes should start with underscore: _internal_state

b. Code Layout:

  • Use 4 spaces for indentation (no tabs)
  • Maximum line length is 88 characters (compatible with black formatter)
  • Add 2 blank lines before top-level classes and functions
  • Add 1 blank line before class methods
  • No trailing whitespace

c. Imports:

  • Imports should be on separate lines: import os\nimport sys
  • Imports should be grouped in the following order:
    1. Standard library imports
    2. Related third party imports
    3. Local application/library specific imports
  • Use absolute imports over relative imports

d. String Formatting:

  • Prefer f-strings for string formatting: f"Count: {count}"
  • Use double quotes for docstrings

e. Type Hints:

  • Use type hints for function arguments and return values
  • Example: def translate_text(text: str) -> str:

f. Documentation:

  • All public functions and classes must have docstrings
  • Use Google style for docstrings

  • Example:

    def function_name(arg1: str, arg2: int) -> bool:
    """Short description of function.

    Args:
        arg1: Description of arg1
        arg2: Description of arg2

    Returns:
        Description of return value

    Raises:
        ValueError: Description of when this error occurs
    """

The existing codebase does not comply with the above specifications in some aspects. Contributions for modifications are welcome.

How to modify the intermediate representation

The intermediate representation is described by il_version_1.rnc. Corresponding Python data classes are generated using xsdata. The files il_version_1.rng, il_version_1.xsd, and il_version_1.py are auto-generated and must not be manually modified.

Format RNC file
trang babeldoc/document_il/il_version_1.rnc babeldoc/document_il/il_version_1.rnc
Generate RNG, XSD and Python classes
# Generate RNG from RNC
trang babeldoc/document_il/il_version_1.rnc babeldoc/document_il/il_version_1.rng

# Generate XSD from RNC
trang babeldoc/document_il/il_version_1.rnc babeldoc/document_il/il_version_1.xsd

# Generate Python classes from XSD
xsdata generate babeldoc/document_il/il_version_1.xsd --package babeldoc.document_il