Documentation options

[wfordh]

IMO the documentation for the package should be moved out of the README and into a new format. It'll make it easier to navigate the docs instead of being a wall of text and will let the README focus on things actually in the scope of a README. The main two options that I know about are:

1. Read the Docs: Clean and "professional" looking. Probably more maintenance as it would require an account and other files. Also the free option comes with ads showing inside the docs. Pulls straight from the docstrings, which is nice because then the documentation automatically updates instead of us needing to update a separate docs file for docstring updates.
2. The markdown option: We'd use raw markdown files, like in the pybaseball package. It might be less "professional", but it would be an easy lift-and-shift job and doesn't have ads. We would need to update the docs files anytime a function docstring changes.

Happy to get any feedback from other users! If I don't get any feedback in the next couple of weeks, then I'll go ahead and move forward with option 2 since it's the path of least resistance at this time. Please note that this is focused on the architecture of the documentation and not the content of the documentation, which should also be addressed.

14

[humitos]

Hi 👋🏼 ! I'm one of the developers working at Read the Docs and I just found this issue, so I wanted to chime in and let you know some changes we've made on Read the Docs in the last months/years that could help you to make a more informed decision:

• It supports any documentation tool you want to use, including Sphinx, MkDocs and Docusaurus, among others
• You can use Markdown to write your documentation
• Paid Ads can be opt-out, and only community ads will be shown in the documentation
• Ads can be completely turned off by paying for a Gold Membership subscription (see https://docs.readthedocs.io/en/stable/advertising/ethical-advertising.html)

Let me know if this information is useful and if you have any doubt where I can be helpful. Thanks!