📝 docs: enhance README, fix issues, and reorganize platforms.rst#445
Merged
gaborbernat merged 11 commits intotox-dev:mainfrom Feb 14, 2026
Merged
📝 docs: enhance README, fix issues, and reorganize platforms.rst#445gaborbernat merged 11 commits intotox-dev:mainfrom
gaborbernat merged 11 commits intotox-dev:mainfrom
Conversation
gaborbernat
force-pushed
the
docs-issue-444
branch
2 times, most recently
from
3c007f2 to
97c219f
Compare
Enhanced README.md to provide MVP documentation for PyPI users without requiring a visit to the full docs. Added comprehensive Quick start showing all directory types (data, config, cache, state, log, runtime, documents, downloads) with Path examples. New Directory types section explains purpose and user vs site variants. Updated Documentation links to reflect the reorganized structure from tox-dev#441 (tutorial, how-to, reference pages). Simplified fork attribution to single line since appdirs has been deprecated since 2023. Fixed api.rst documentation: - Added missing user_applications_dir and user_bin_dir documentation - Unified headlines to use "User X directory" format consistently - Added bi-directional cross-references between api.rst and platforms.rst Reorganized platforms.rst to match api.rst structure: - Grouped all user directories together under "User directories" section - Grouped all site directories together under "Shared directories" section - Reordered to match api.rst sequence (runtime/applications/bin before documents/downloads for better alignment) - Added bi-directional cross-references to api.rst sections Fixed howto.rst: - Removed non-existent PLATFORMDIRS_* env variable reference - Updated cross-reference to Windows environment overrides Fixed parameters.rst: - Resolved XDG documentation redundancy by linking to howto.rst - Added cross-reference to Windows environment overrides - Added explicit label for XDG environment variables section All documentation cross-references now work correctly and docs build passes without warnings. Addresses tox-dev#444
gaborbernat
force-pushed
the
docs-issue-444
branch
from
c1ec97a to
5b48a5a
Compare
for more information, see https://pre-commit.ci
gaborbernat
changed the title
The appdirs fork history is no longer relevant since the original project was deprecated in 2023. Removed the fork attribution text and replaced it with a direct link to CONTRIBUTING.md to make it easier for new contributors to find guidelines.
gaborbernat
force-pushed
the
docs-issue-444
branch
from
1fbedeb to
faaae85
Compare
for more information, see https://pre-commit.ci
Prettier is a JavaScript tool that requires Node.js dependencies. Switching to yamlfmt for YAML files and mdformat for Markdown provides better integration with Python tooling and reduces cross-language dependencies. mdformat with gfm and black plugins provides equivalent formatting for Markdown files with 120 character wrapping, while yamlfmt handles YAML formatting natively without additional configuration.
gaborbernat
force-pushed
the
docs-issue-444
branch
2 times, most recently
from
00bdac3 to
fe26381
Compare
The previous CONTRIBUTING.md was minimal. Expanded it to provide clear guidance for new contributors with tox-based workflows for testing, linting, type checking, and documentation building. Structured around tox commands since all development tasks use tox environments, making it easier for contributors to get started and follow the project's development practices. Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
gaborbernat
force-pushed
the
docs-issue-444
branch
from
fe26381 to
8b0f02d
Compare
Updated tox-toml-fmt to v1.6.0, pyproject-fmt to v2.16.0, and ruff-pre-commit to v0.15.1. Added yamlfmt for YAML formatting and mdformat with plugins for Markdown formatting to replace prettier. Excluded release.yaml from yamlfmt due to pre-existing formatting issues with multiline template expressions.
Fixed GitHub Actions workflow files to use clean, readable formatting instead of folded scalar syntax with blank lines. Removed unnecessary line breaks from concurrency group and changelog command definitions. The >- (folded scalar) syntax with blank lines was confusing and hard to format. yamlfmt properly collapses these to single lines while preserving the actual string values that GitHub Actions receives.
Converted the contributing guide from structured lists and sections to flowing prose with proper English grammar and punctuation. Information is presented in narrative form while maintaining the same tox-focused content and comprehensive guidance for contributors.
Converted the contributing guide from structured lists and sections to flowing prose with proper English grammar and punctuation. Information is presented in narrative form while maintaining the same tox-focused content and comprehensive guidance for contributors.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PyPI users need MVP documentation directly in the README without visiting the full docs. The previous README showed only a few directories without explaining their purpose. After PR #441 reorganized documentation into tutorial/how-to/reference pages, several issues remained: the README still referenced the old structure, api.rst was missing documentation for new properties, platforms.rst had a mixed organization that didn't match api.rst, and various cross-references were broken.
This comprehensive update enhances the README with all directory types (data, config, cache, state, log, runtime, documents, downloads) and Path examples. A new Directory types section explains purpose and
user_*vssite_*variants. 📖 The fork attribution is simplified to one line since appdirs has been deprecated since 2023.The api.rst now documents previously missing
user_applications_diranduser_bin_dirproperties with unified headlines using "User X directory" format. The platforms.rst is reorganized to match api.rst structure with all user directories grouped together and all site directories grouped together in the same order as api.rst. ✨ Bi-directional cross-references connect api.rst and platforms.rst sections so users can easily navigate between API reference and platform-specific paths.Additional fixes resolve XDG documentation redundancy through cross-references, remove non-existent PLATFORMDIRS_* environment variable mentions, and ensure all documentation builds without warnings.
Addresses #444