Some minor documentation issues and suggestions:
- Issues
- Suggestions
docs/api.rst: Unify headlines (e.g., "User data directory" for user_data_dir vs. just "Cache directory" for user_cache_dir, IMHO should be "User cache directory" et. al.)docs/api.rst: Move user_runtime_dir, user_applications_dir, and user_bin_dir in front of user_documents_dir et. al. to not disrupt the shared order with the site_*_dir method listdocs/platforms.rst: Group the user_*_dir methods into a "User directories" section, and the site_*_dir methods into a "Shared directories" section, matching docs/api.rst; also use the same method order as docs/api.rstdocs/api.rst and docs/platforms.rst: Maybe add reference links to the matching section of the same method to both pages (e.g., add a link to platforms.html#user-cache-dir in the user_cache_dir section of docs/api.rst, and vice-versa)docs/parameters.rst: The XDG_* env variables are explained in a section there, but not the WIN_PD_OVERRIDE_* env variables; make sure not to create too many redundancies with the existing class docs in docs/api.rst, the sections - also including the "Windows" -> "Environment variable overrides" section in docs/howto.rst - should rather reference and link to each otherdocs/howto.rst and docs/parameters.rst: There's some redundancy between the "Linux / Unix" -> "XDG Base Directory Specification" section of docs/howto.rst, the "XDG environment variables" section of docs/parameters.rst, and the class docs in docs/api.rst; some redundancies are expected and feasible, but IMHO not to this extent; the sections should rather reference and link to each other
- Other
- Do the
PLATFORMDIRS_* env variables actually still exist? I'm not entirely sure, but I guess not? Because they are still mentioned in docs/howto.rst, but nowhere else. If they were never actually released, they should also be removed from the changelog.
Some minor documentation issues and suggestions:
README.md: The chapters in theDocumentationsection weren't updated after merging 📚 docs: split usage guide into tutorial, how-to, and reference #441; alternatively, the chapters could also simply be removed, a link to https://platformdirs.readthedocs.io is sufficient IMHO (already mentioned in 📚 docs: split usage guide into tutorial, how-to, and reference #441 (comment))docs/api.rst: Documentation ofsite_applications_dir(✨ feat(api): add site_applications_dir property #442) is missingdocs/api.rst: Documentation ofsite_bin_dir(✨ feat(api): add site_bin_dir property #443) is missingdocs/platforms.rst: Remove the "Environment variable overrides" headline below the "Windows" section (this sub-section otherwise also includes e.g. the class docs, IMHO the sub-section headline simply isn't necessary, there's none for Unix either)docs/api.rst: Unify headlines (e.g., "User data directory" foruser_data_dirvs. just "Cache directory" foruser_cache_dir, IMHO should be "User cache directory" et. al.)docs/api.rst: Moveuser_runtime_dir,user_applications_dir, anduser_bin_dirin front ofuser_documents_diret. al. to not disrupt the shared order with thesite_*_dirmethod listdocs/platforms.rst: Group theuser_*_dirmethods into a "User directories" section, and thesite_*_dirmethods into a "Shared directories" section, matchingdocs/api.rst; also use the same method order asdocs/api.rstdocs/api.rstanddocs/platforms.rst: Maybe add reference links to the matching section of the same method to both pages (e.g., add a link toplatforms.html#user-cache-dirin theuser_cache_dirsection ofdocs/api.rst, and vice-versa)docs/parameters.rst: TheXDG_*env variables are explained in a section there, but not theWIN_PD_OVERRIDE_*env variables; make sure not to create too many redundancies with the existing class docs indocs/api.rst, the sections - also including the "Windows" -> "Environment variable overrides" section indocs/howto.rst- should rather reference and link to each otherdocs/howto.rstanddocs/parameters.rst: There's some redundancy between the "Linux / Unix" -> "XDG Base Directory Specification" section ofdocs/howto.rst, the "XDG environment variables" section ofdocs/parameters.rst, and the class docs indocs/api.rst; some redundancies are expected and feasible, but IMHO not to this extent; the sections should rather reference and link to each otherPLATFORMDIRS_*env variables actually still exist? I'm not entirely sure, but I guess not? Because they are still mentioned indocs/howto.rst, but nowhere else. If they were never actually released, they should also be removed from the changelog.