Closed pushfoo closed 1 year ago
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:
dev-requirements.txt
locatedarcade
as an editable package with pip install -e
setup.py
sudo ./make.sh
to make a local installmake.bat
appear to be more fully featuredhttps://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md
https://api.arcade.academy/en/latest/development/how_to_contribute.html
Thanks. This is a great list.
@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:
venv
module for this)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.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.
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.
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.
Some things that would be helpful for beginners working with documentation:
python -m http.server --directory doc\build\html
or similar (search works with this btw!)@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.
Sure. Feel free to work on whatever improvements you can see related to this. Main thing I've done is improve Linux install instructions.
Are your changes merged? I looked back through a few pages of recent commits and didn't see anything related to this.
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.
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.
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?
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: