Skip to content
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

Remove documentation from readme and instead forward to the readthedocs one #28

Open
gaborbernat opened this issue Jul 23, 2021 · 7 comments
Labels
help wanted Extra attention is needed

Comments

@gaborbernat
Copy link
Member

gaborbernat commented Jul 23, 2021

👍 https://platformdirs.readthedocs.io/en/latest/

@gaborbernat gaborbernat added the help wanted Extra attention is needed label Jul 23, 2021
@papr
Copy link
Contributor

papr commented Jul 28, 2021

What type of forwarding did you have in mind? Is the link in the repo description sufficient? Or should there be a minimal readme linking to the link above?

@Julian
Copy link
Contributor

Julian commented Aug 24, 2021

@papr a minimal (1-2 paragraph) README sending someone to the docs is probably the right idea.

@PhrozenByte
Copy link

In the past two years README.rst became even more outdated: It mentions neither site_cache_dir(), nor user_state_dir(), or site_runtime_dir(). For Windows it shows the C:\Documents and Settings\<User>\Application Data structure from Windows XP as examples.

However, README.rst generally explains the usage better:

  • It includes example outputs (which makes it easier to find the right method)
  • It explains the different usage types ({site,user}_*_{dir,path}() methods vs. PlatformDirs class)
  • It better explains advanced features, like version, multipath, or switching to roaming on Windows

So, platformdirs should either keep an updated README.rst and add a link to the API docs, or should move all parts (including the descriptive parts) of README.rst to the API docs.

@gaborbernat
Copy link
Member Author

PR welcome for the later.

@sarnold
Copy link

sarnold commented Sep 20, 2023

Somehow "moving" doesn't sound like the best answer? I agree with the "readme explains more" in general, it just needs to be kept up-to-date, eg, usr_log_dir in the Linux section does not match the actual dir path. That said, my usual approach to docs in general is to put a symlink to the readme file in the docs source directory and just use it for the main docs page like this. Maybe that's an option?

@gaborbernat
Copy link
Member Author

I disagree on this, I prefer the index just link to the documentation page and that's it.

@sarnold sarnold mentioned this issue Sep 20, 2023
@sarnold
Copy link

sarnold commented Sep 20, 2023

Oh, i just made the path fix and example docs PR. It does look pretty good to my eye anyway...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

5 participants