Improve documentation on how to develop and contribute to Arcade

[pushfoo]

Documentation request:

What documentation needs to change?

The beginner developer documentation needs to be improved.

Where is it located?

The how to contribute page page.

What is wrong with it? How can it be improved?

1. Organize the page better with clearer steps and sections
2. Add mention of how to run mypy and flake8 locally to save time before making a PR

Update

This issue is being expanded to cover updating documentation across the board for how people can get started developing for Arcade and guidelines for making contributions.

This includes but isn't necessarily limited to:

• Clarifying venv usage
• How to do an editable install from source(including with dev dependencies)
• How to run tests
• How to build documentation and view it locally
• Maybe also cover the forking/PR process if people are unfamiliar? Or some basic git usage in general? There may be people unfamiliar with it that just want to contribute to some docs fixes or something.
• Maybe re-visit and update/consolidate the make scripts to be usable on platforms other than Windows and ensure they're up to date.

[rckwzrd]

As a beginner developer and linux user... Here are a few thoughts on improvement.

The how to compile section in the docs has reasonably detailed instructions for Windows. The linux portion simply has the line sudo apt-get install python-dev. I do not really know what this means. Perhaps higher level of expertise is assumed for linux users (does not apply to me :) ).

There also seems to be some conflict between the CONTRIBUTING.md and the how to contribute section in the docs. There is no mention of make.sh in the docs... but it is in CONTRIBUTING.md.

I am not a bash expert but make.sh appears to be uninstalling arcade and then installing files from /dist. Can why this is done be explained? Perhaps it has something to do with setup.py bdist_wheel.

It would be helpful to provide reasonably detailed instructions for cloning, forking and building a local install of arcade from the remote repo hosted on github. Also providing a brief "why" for each step would help instill a bit of knowledge for the new developer.

Specifically I found myself wondering:

• where are dev-requirements.txt located
• should I install arcade as an editable package with pip install -e
• do I need to interact with setup.py
• is there a preferred virtual environment to house a local arcade install
• do I need to run sudo ./make.sh to make a local install
• how do I run unit tests with pytest, mypy, and flake8
• do I need to test docs
• why does the windows make.bat appear to be more fully featured

https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md

https://api.arcade.academy/en/latest/development/how_to_contribute.html

[einarf]

Thanks. This is a great list.

[Cleptomania]

@mlr07 Thanks for the feedback, that's really useful info.

Linux is my primary OS and what I develop from most of the time so I can definitely do some work on improving the Linux specific instructions.

Some notes on a few of the points presented, and the general direction of things:

• We should stress virtual environment usage within this, a lot of people don't even know about them, let alone how and why to use them. (I believe most of us just use python's built-in venv module for this)
• We should always be recommending editable installs using pip install -e ".[dev]". Adding the dev tag there ensures that mypy, flake8, sphinx, pytest, etc get installed. All dependencies are controlled via the setup.py file which that will automatically use. We don't use requirements.txt at all anymore.
• There is no real need to use the make scripts if you're familiar with commands directly, but maybe the make scripts can be updated and consolidated and everything to make it easier to interact with? I lean towards documenting how to interact without the use of make scripts as it would help new contributors to understand what's really happening easier.

[rckwzrd]

Thanks for the additional feedback.

For the virtual environments I have been using the virtualvenv plugin for pyenv. I am pretty sure pyenv-virtualenv just wraps venv.

Does moving away from requirements.txt and using setup.py to pull dependancies allow for smooth packaging and deployment to PyPI?

For learning, I would like to see the procedural commands to get arcade up and running. Maybe a section could be dedicated to manual interaction. Then a following section for make scripts. An alternative might be to depreciate the make scripts all together. I don't know how this would effect the wider project and community though.

[Cleptomania]

The advantages of setup.py vs requirements.txt is really just flexibility. With a requirements file you really can just specify packages and versions. With setup.py we do a number of things, have dynamic descriptions, versions, etc, but also get the benefit of conditional dependencies.

We're able to define for example installing dataclasses if you're on python 3.6, and currently we don't have to do this, but there were times when numpy was a dependency, and we had to have different versions of numpy based on what OS you were on if you were on Python 3.9. We're able to achieve a lot of flexibility with setup.py, and it puts us closer in line with where the greater Python community is moving for dependency/build system management.

As for the status of the make scripts, @pvcraven would have to comment on that more. I personally don't use the make scripts at all, but I'm also not the one who handles the releases, and I'm not certain what other people are doing in their own specific setups.

[pushfoo]

I think one more crucial thing we need in the beginner docs is where to put constructor argument doc. I ran across #1005 while trying to address #985 , and it seems to have arisen because the standard either wasn't clear or classes haven't been moved to the new style yet.

I also started documenting arcade.Text in the wrong way for #985 before @pvcraven cleared the issue up for me on discord. Giving this info to beginners from the start would be good. Also maybe adding a CI check to detect newly added params in constructor docstrings once we fix all the existing ones.

[pushfoo]

Some things that would be helpful for beginners working with documentation:

1. explain how to preview the generated documentation with python -m http.server --directory doc\build\html or similar (search works with this btw!)
2. find and link good sphinx rst reference for beginners. there are multiple styles supported, and it help beginners if we point them to the correct one.
3. A page that outlines what this project's guidelines for doc are

[pushfoo]

@Cleptomania Can we turn this into a task list that links other tickets? It's very broad in scope, and I'd be willing to take a few tickets from it while you work on pytiled.

[Cleptomania]

Sure. Feel free to work on whatever improvements you can see related to this. Main thing I've done is improve Linux install instructions.

[pushfoo]

Are your changes merged? I looked back through a few pages of recent commits and didn't see anything related to this.

[Cleptomania]

Yeah it's been a while, I think I have a few things in a local branch but I've been sidetracked for a while so I don't even remember exactly what I have. You're good to start working on anything.

[Cleptomania]

I think with our switch to make.py and associated CONTRIBUTING guidelines we are in a pretty solid place for this. I'm going to close this issue but if anyone feels it still needs something done feel free to re-open, or just make a new issue that's more specific is probably better.