The documentation for the human-errors package currently gives a solid overview but could benefit from enhanced direction and clarity—especially for new adopters and for expanding use-cases. Improving the docs will make the project more accessible and encourage contributions.
What needs improvement
-
The README and PyPI project description cover usage of json_dump, toml_dump, yaml_dump, and the CLI tool, but some sections lack step-by-step detailed examples for typical workflows (e.g., integrating with a CI pipeline, custom renderer use).
-
Formatting and structure vary between sections: headings, code blocks, and outputs could be more consistently styled (for example, unified indenting, consistent use of language comments, and clearer context).
-
The “Contributing” section exists (under Contributing on PyPI) but could be expanded: describe local setup (linting with ruff, type checking with ty, tests with pytest), branch naming, PR review criteria, and how to add new format support.
PyPI
-
Compatibility/version information is minimal: while the package “Requires: Python >=3.12” is listed, it would help to document any differences/limitations when using Python 3.13+, or if certain renderers (like the miette-style) require extra setup.
PyPI
-
Navigation could be improved: a table of contents or sidebar (if using a docs-site generator) would help locate examples, CLI usage, and custom renderer docs faster.
Proposed improvements
Update the README to reflect:
-
latest installation steps (pip install human-errors)
-
typical usage patterns (parsing a config file, catching a decode error, using the CLI tool)
-
show full code snippet + output in a consistent format
-
Add a “Getting Started” section for newcomers with links to full examples for JSON, TOML, YAML, CLI
-
Standardise headings and formatting across docs: e.g., use ## for main sections, ### for sub‐sections, wrap code blocks with language specifier (```python)
-
Expand the “Contributing” section: local dev setup, lint/format commands, how to run tests, how to add support for a new file format
-
Add a section “Version & Compatibility” to document Python version support, note any known caveats or future plans
-
If desired, create a simple docs site navigation or table of contents (could be added in the README or a docs / docs-site folder) for “Installation | Usage | CLI | Custom Renderer | Contributing | Version Info”
Additional context
I’d be happy to tackle this and submit a pull request. Please let me know if you have any style guidelines or preferred docs tooling (Markdown only vs MkDocs/Sphinx) so I can align with the project’s standards.
Thanks and Regards,
Revanth Arunachalam,
Python and Ladder.
The documentation for the human-errors package currently gives a solid overview but could benefit from enhanced direction and clarity—especially for new adopters and for expanding use-cases. Improving the docs will make the project more accessible and encourage contributions.
What needs improvement
The README and PyPI project description cover usage of json_dump, toml_dump, yaml_dump, and the CLI tool, but some sections lack step-by-step detailed examples for typical workflows (e.g., integrating with a CI pipeline, custom renderer use).
Formatting and structure vary between sections: headings, code blocks, and outputs could be more consistently styled (for example, unified indenting, consistent use of language comments, and clearer context).
The “Contributing” section exists (under Contributing on PyPI) but could be expanded: describe local setup (linting with ruff, type checking with ty, tests with pytest), branch naming, PR review criteria, and how to add new format support.
PyPI
Compatibility/version information is minimal: while the package “Requires: Python >=3.12” is listed, it would help to document any differences/limitations when using Python 3.13+, or if certain renderers (like the miette-style) require extra setup.
PyPI
Navigation could be improved: a table of contents or sidebar (if using a docs-site generator) would help locate examples, CLI usage, and custom renderer docs faster.
Proposed improvements
Update the README to reflect:
latest installation steps (pip install human-errors)
typical usage patterns (parsing a config file, catching a decode error, using the CLI tool)
show full code snippet + output in a consistent format
Add a “Getting Started” section for newcomers with links to full examples for JSON, TOML, YAML, CLI
Standardise headings and formatting across docs: e.g., use ## for main sections, ### for sub‐sections, wrap code blocks with language specifier (```python)
Expand the “Contributing” section: local dev setup, lint/format commands, how to run tests, how to add support for a new file format
Add a section “Version & Compatibility” to document Python version support, note any known caveats or future plans
If desired, create a simple docs site navigation or table of contents (could be added in the README or a docs / docs-site folder) for “Installation | Usage | CLI | Custom Renderer | Contributing | Version Info”
Additional context
I’d be happy to tackle this and submit a pull request. Please let me know if you have any style guidelines or preferred docs tooling (Markdown only vs MkDocs/Sphinx) so I can align with the project’s standards.
Thanks and Regards,
Revanth Arunachalam,
Python and Ladder.