📝 Documentation Overhaul 🚧

[py-mine-bot]

Authored by kevinkjt2000
Jun 10, 2021

---

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 #425
• Redo the main README to summarize the project's overall goal, link to readthedocs, badges (GitHub CI status, pypi), and explain how to contribute #426
• Make sure the README is copied to pypi long description metadata #427
• Use pytest for running doctests to include tested examples within docstrings
• Add an example for Bedrock (I wonder if it supports Bedrock Edition #153)
• Give examples for decoding ISO 8859-1 into UTF-8 (otherwise, people are surprised with garbage characters If the server name is Korean, the server name cannot be printed out in Korean. #99 Cyrillic characters in names shown incorrectly #138)
• Setup issue templates on GitHub that include a read-these-common-things message to cut down on the number of Invalid issues #691
• Type hints on everything (also enforce these during CI) (there's already some progress on this Docstrings and typehints #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. Is there documentation?  #131)
• Explain that most functions offer an async version (Using the library asynchronously #171)
• Make it clear that player lists are often incomplete because of server plugins and custom implementations
• Document how to get the server info png image (How to get this? #160)
• Document possible exceptions Document possible exceptions #692
• Document windows asyncio event loop close bug #693

[py-mine-bot]

Authored by ItsDrike
Jan 5, 2022

---

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.

[py-mine-bot]

Authored by Izergaer
Nov 3, 2021

---

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

[py-mine-bot]

Authored by kevinkjt2000
Nov 3, 2021

---

@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 https://github.com/Dinnerbone/mcstatus/blob/10cea643fa3866063c6b5b327fe890213ecee7f2/mcstatus/scripts/mcstatus.py#L56

[PerchunPak]

I took it in #450.

[PerchunPak]

Looked again and checked those points which are done now, other ones don't worth resolving/moved to its own issue (such as #307).

Maybe close this?

[ItsDrike]

I agree, let's make these new issues:

• Document possible exceptions that need to be handled
• Warn about a Windows-specific bug that arises from deep within asyncio socket stuff (assuming that it still is a problem, which I'm not actually sure of)
• Setup issue templates on GitHub that include a read-these-common-things message to cut down on the number of Invalid issues

As for the doctests, I don't think this is too important for us now, although an issue could be opened about it, I'm neither for nor against.

Once done, the links to these issues should be mentioned in a closing comment for this.

[kevinkjt2000]

I mentioned issue numbers in the initial comment next to each item. I concur with leaving out doctests for now.