Giters

Dinnerbone / mcstatus

A Python class for checking the status of an enabled Minecraft server

Home Page:http://dinnerbone.com/minecraft/tools/status/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

📝 Documentation Overhaul 🚧

kevinkjt2000 opened this issue · comments

commented

I have seen several issues asking for an online/offline feature or pasting a stacktrace of a timeout exception. Honestly, I'm surprised at the number of people that would install an extra library without understanding basic exception handling in Python, but I digress. There also have been feature requests that have nothing to do with what mcstatus is even about (such as RCON support). Well, we all start somewhere and I'm certain we could foster a more welcoming onboarding experience and a better user experience by overhauling the documentation for mcstatus.

Sorted by highest priority for the project, this is my opinionated list of things to do to improve the user experience:

  • Host documentation on readthedocs.org
  • Redo the main README to summarize the project's overall goal, link to readthedocs, badges (travis CI status, pypi), and explain how to contribute
  • Make sure the README is copied to pypi long description metadata
  • Use pytest for running doctests to include tested examples within docstrings
  • Add an example for Bedrock (#153)
  • Give examples for decoding ISO 8859-1 into UTF-8 (otherwise, people are surprised with garbage characters #99 #138)
  • Setup issue templates on GitHub that include a read-these-common-things message to cut down on the number of Invalid issues
  • Type hints on everything (also enforce these during CI) (there's already some progress on this #111 if I would stop playing so much Minecraft and take the time to review/merge it)
  • List properties that are included on response objects (people shouldn't have to use dir to see what attributes an object has e.g. #131)
  • Explain that most functions offer an async version (#171)
  • Document how to get the server info png image (#160)
  • Document possible exceptions that need to be handled (e.g. timeout #77 #97 #129 #135, ConnectionResetError #101, ConnectionRefusedError, gaierror, maybe custom exception wrappers in the future)
  • Warn about a Windows-specific bug that arises from deep within asyncio socket stuff encode/httpx#914 (comment)
commented

Is it possible to know usernames of players who playing on server rn? I apologize if this is already there, but I cannot find documentation about it

commented

@Izergaer The readme has an example that shows how to get player names from the query response. It's also possible to get player names from status. The CLI that comes with this library does both too

mcstatus/mcstatus/scripts/mcstatus.py

Line 56 in 10cea64

def status():

commented

Give examples for decoding ISO 8859-1 into UTF-8 (otherwise, people are surprised with garbage characters

Why are we not doing this automatically? Is there some benefit in keeping it in ISO 8859-1? I feel like this will only cause more issues to appear over time as people won't know what's going on since it's non-trivial to figure out. Even when documented, it would just clutter the docs when we could easily do this on the library side.