Updating API Documentation

jackdewinter commented 1 month ago

https://github.com/jackdewinter/pymarkdown/issues/1226

Updating API documentation to make it easier to use.

Summary by Sourcery

Update API documentation and enhance markdown processing by adding detailed method descriptions and handling special cases in list spacing. Improve test coverage with new test cases for nested markdown structures. Update changelog and test result documentation to reflect recent changes.

Enhancements:

Enhance the API documentation in pymarkdown/api.py by adding detailed descriptions of parameters, exceptions, and return values for various methods to improve usability and clarity.
Improve the pymarkdown/plugins/rule_md_031.py by adding new methods to handle special cases in list spacing and adjusting container adjustments for better markdown processing.

Documentation:

Update the API documentation in docs/api.md to include detailed method descriptions, parameters, exceptions, and return values, enhancing the clarity and usability of the documentation.

Tests:

Add new test cases in test/rules/test_md031.py and test/test_markdown_extra.py to cover additional scenarios and ensure the correctness of markdown processing, particularly for nested structures and special cases.

Chores:

Update publish/coverage.json and publish/test-results.json to reflect the latest test coverage and results, including changes in the number of tests and skipped tests.
Modify newdocs/src/changelog.md to include references to issues 1166, 1167, and 1168, documenting fixes for deeply nested markdown issues.

sourcery-ai[bot] commented 1 month ago

Reviewer's Guide by Sourcery

This pull request updates the API documentation for the PyMarkdown project, enhancing its usability. The changes primarily focus on adding detailed documentation to various methods in the PyMarkdownApi class, including parameter descriptions, return values, and exceptions. Additionally, there are some bug fixes and improvements to the test suite and related files.

Class diagram for PyMarkdownApi with updated documentation

classDiagram
    class PyMarkdownApi {
        - bool inherit_logging
        + str application_version()
        + int interface_version()
        + PyMarkdownApi enable_stack_trace()
        + PyMarkdownApi log_debug_and_above()
        + PyMarkdownApi log_info_and_above()
        + PyMarkdownApi log_warning_and_above()
        + PyMarkdownApi log_error_and_above()
        + PyMarkdownApi log_critical_and_above()
        + PyMarkdownApi log(str log_level)
        + PyMarkdownApi log_to_file(str log_file_path)
        + PyMarkdownApi add_plugin_path(str path_to_plugin)
        + PyMarkdownApi configuration_file_path(str path_to_config_file)
        + PyMarkdownApi set_boolean_property(str property_name, bool property_value)
        + PyMarkdownApi set_integer_property(str property_name, int property_value)
        + PyMarkdownApi set_string_property(str property_name, str property_value)
        + PyMarkdownApi set_property(str property_name, Any property_value)
        + PyMarkdownApi enable_strict_configuration()
        + PyMarkdownApi disable_rule_by_identifier(str rule_identifier)
        + PyMarkdownApi enable_rule_by_identifier(str rule_identifier)
        + PyMarkdownListPathResult list_path(str path_to_scan, bool recurse_if_directory, str alternate_extensions)
        + PyMarkdownScanPathResult scan_path(str path_to_scan, bool recurse_if_directory, Any alternate_extensions)
        + PyMarkdownFixResult fix_path(str path_to_scan, bool recurse_if_directory, Any alternate_extensions)
    }

File-Level Changes

Change	Details	Files
Enhanced API documentation for PyMarkdownApi class methods	Added detailed parameter descriptions Included return value information Added exception details for various methods Improved method summaries	`pymarkdown/api.py` `docs/api.md`
Fixed issues with nested structures in Markdown parsing	Addressed problems with deeply nested structures Improved handling of list starts grouped on the same line Updated test cases to cover new scenarios	`pymarkdown/plugins/rule_md_031.py` `test/rules/test_md031.py` `test/test_markdown_extra.py`
Updated test suite and related files	Modified test cases to reflect API changes Updated coverage and test result files Adjusted profiling command	`test/api/test_api_scan.py` `publish/coverage.json` `publish/test-results.json` `prof_list.cmd`
Updated changelog and documentation generation	Added new issue references to the changelog Modified documentation generation script	`newdocs/src/changelog.md` `utils/correct_pdoc_issues.py`

Tips and commands

#### Interacting with Sourcery - **Trigger a new review:** Comment `@sourcery-ai review` on the pull request. - **Continue discussions:** Reply directly to Sourcery's review comments. - **Generate a GitHub issue from a review comment:** Ask Sourcery to create an issue from a review comment by replying to it. - **Generate a pull request title:** Write `@sourcery-ai` anywhere in the pull request title to generate a title at any time. - **Generate a pull request summary:** Write `@sourcery-ai summary` anywhere in the pull request body to generate a PR summary at any time. You can also use this command to specify where the summary should be inserted. #### Customizing Your Experience Access your [dashboard](https://app.sourcery.ai) to: - Enable or disable review features such as the Sourcery-generated pull request summary, the reviewer's guide, and others. - Change the review language. - Add, remove or edit custom review instructions. - Adjust other review settings. #### Getting Help - [Contact our support team](mailto:support@sourcery.ai) for questions or feedback. - Visit our [documentation](https://docs.sourcery.ai) for detailed guides and information. - Keep in touch with the Sourcery team by following us on [X/Twitter](https://x.com/SourceryAI), [LinkedIn](https://www.linkedin.com/company/sourcery-ai/) or [GitHub](https://github.com/sourcery-ai).

codecov[bot] commented 1 month ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 100.00%. Comparing base (2bce8ca) to head (71b255c). Report is 1 commits behind head on main.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #1227 +/- ## ======================================== Coverage 99.99% 100.00% ======================================== Files 191 191 Lines 21048 21037 -11 Branches 2687 2683 -4 ======================================== - Hits 21046 21037 -9 + Misses 1 0 -1 + Partials 1 0 -1 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

jackdewinter / pymarkdown