Skip to content

Add API reference documentation using mkdocstrings #355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

lebrice
Copy link
Owner

@lebrice lebrice commented Jun 3, 2025

This commit enhances the MkDocs documentation by:

  1. Adding mkdocstrings[python] to handle auto-generation of API documentation from Python docstrings.
  2. Configuring mkdocstrings in mkdocs.yml under the plugins section and updating the navigation to include an "API Reference" section.
  3. Creating docs/api_reference.md with directives to generate documentation for key modules and classes in simple_parsing including:
    • simple_parsing.parsing
    • simple_parsing.helpers.serialization.serializable.Serializable
    • simple_parsing.wrappers.dataclass_wrapper
    • simple_parsing.wrappers.field_wrapper
    • simple_parsing.ArgumentParser
    • simple_parsing.helpers.hparams
  4. Removing extraneous files (=1.0, =7.0) that were accidentally created in the repository root.

The documentation now includes both the examples and a browsable API reference.

This commit enhances the MkDocs documentation by:
1. Adding `mkdocstrings[python]` to handle auto-generation of API documentation from Python docstrings.
2. Configuring `mkdocstrings` in `mkdocs.yml` under the `plugins` section and updating the navigation to include an "API Reference" section.
3. Creating `docs/api_reference.md` with directives to generate documentation for key modules and classes in `simple_parsing` including:
    - `simple_parsing.parsing`
    - `simple_parsing.helpers.serialization.serializable.Serializable`
    - `simple_parsing.wrappers.dataclass_wrapper`
    - `simple_parsing.wrappers.field_wrapper`
    - `simple_parsing.ArgumentParser`
    - `simple_parsing.helpers.hparams`
4. Removing extraneous files (`=1.0`, `=7.0`) that were accidentally created in the repository root.

The documentation now includes both the examples and a browsable API reference.
@lebrice lebrice requested a review from Copilot June 3, 2025 00:13
Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR enhances the project documentation by integrating mkdocstrings for auto-generating API reference docs and by adding various example scripts that demonstrate advanced configuration, aliasing, and ML use-cases with simple-parsing. Key changes include:

  • Adding mkdocstrings support via the new docs/api_reference.md file.
  • Introducing new example files for container types, configuration files, alias handling, and ML scripts.
  • Removing extraneous root files that were mistakenly created.

Reviewed Changes

Copilot reviewed 68 out of 68 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
docs/api_reference.md New file that auto-generates the API reference using mkdocstrings.
docs/examples/container_types/*.py Examples demonstrating parsing of container-type arguments with simple_parsing.
docs/examples/config_files/* New YAML and Python examples showcasing configuration file usage and composition.
docs/examples/aliases/*.py and docs/examples/aliases/README.md Samples and detailed documentation for using argument aliases with the parser.
docs/examples/ML/*.py and docs/examples/ML/README.md Before/after examples for ML scripts transitioning from argparse to simple_parsing.

Copy link

codecov bot commented Jun 3, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 86.29%. Comparing base (2a69ceb) to head (4b1e5fe).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #355   +/-   ##
=======================================
  Coverage   86.29%   86.29%           
=======================================
  Files          34       34           
  Lines        4554     4554           
=======================================
  Hits         3930     3930           
  Misses        624      624           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant