From 47c794dc9073d69c727db7c1b8e1c6bbbc7fc32d Mon Sep 17 00:00:00 2001 From: Darren Eberly Date: Tue, 12 Dec 2023 01:19:27 -0500 Subject: [PATCH 1/4] Convert README and CONTRIBUTING to Markdown --- CONTRIBUTING.rst => CONTRIBUTING.md | 177 +++++++++++++--------------- README.rst => README.md | 37 ++---- 2 files changed, 93 insertions(+), 121 deletions(-) rename CONTRIBUTING.rst => CONTRIBUTING.md (50%) rename README.rst => README.md (59%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.md similarity index 50% rename from CONTRIBUTING.rst rename to CONTRIBUTING.md index 27a8e80ac..97baa45cd 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.md @@ -1,23 +1,23 @@ -Contributing to Arcade -====================== +# Contributing to Arcade Arcade welcomes contributions, including: -* `Bug reports & feature suggestions `_ +* [Bug reports & feature suggestions](https://github.com/pythonarcade/arcade/issues) * Bug fixes * Implementations of requested features * Corrections & additions to the documentation * Improvements to the tests If you're looking for a way to contribute, try checking -`the currently active issues `_ -for one that needs work. +[the currently active issues](https://github.com/pythonarcade/arcade/issues>) +for one that needs work. If you're new to programming or contributing, check for the +label `good first issue`, these are issues which have been identified as good candidates +for first time contributors. -Before Making Changes ---------------------- +## Before Making Changes Before working on an improvement, please make sure to -`open an issue `_ if one +[open an issue](https://github.com/pythonarcade/arcade/issues) if one does not already exist for it. Tips: @@ -25,67 +25,61 @@ Tips: 1. Try to keep individual PRs to reasonable sizes 2. If you want to make large changes, please discuss them with Arcade's developers beforehand -Discussion can happen in a GitHub issue's comments or on `Arcade's Discord server `_. +Discussion can happen in a GitHub issue's comments or on [Arcade's Discord server](https://discord.gg/ZjGDqMp). -After Making Changes --------------------- +## After Making Changes After you finish your changes, you should do the following: -1. Test your changes according to the :ref:`Testing` section below +1. Test your changes according to the [Testing](#testing) section below 2. Submit a - `pull request `_ + [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests>) from your fork to Arcade's development branch. The rest of the guide will help you get to this point & explain how to test in more detail. -Requirements ------------- +## Requirements Although using arcade only requires Python 3.8 or higher, development currently requires 3.9 or higher. The rest of this guide assumes you've already done the following: -1. `Installed Python 3.9+ with pip `_ -2. `Installed git `_ -3. `Forked the repo on GitHub `_ -4. `Cloned your fork locally `_ +1. [Installed Python 3.9+ with pip](https://wiki.python.org/moin/BeginnersGuide/Download) +2. [Installed git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +3. [Forked the repo on GitHub](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) +4. [Cloned your fork locally](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) 5. Changed directories into your local Arcade clone's folder -`Creating & using a virtual environment `_ +[Creating & using a virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments) is also strongly recommended. -Installing Arcade in Editable Mode ----------------------------------- +## Installing Arcade in Editable Mode To install all necessary development dependencies, run this command in your terminal from inside the top level of the arcade directory: -.. code-block:: shell - - pip install -e '.[dev]' +```bash +pip install -e '.[dev]' +``` If you get an error like the one below, you probably need to update your pip version: -.. code-block:: text - - ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: /home/user/Projects/arcade - (A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.) +``` +ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: /home/user/Projects/arcade +(A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.) +``` Upgrade by running the following command: -.. code-block:: shell - - pip install --upgrade pip +```bash +pip install --upgrade pip +``` Mac & Linux users can improve their development experience further by following the optional steps at the end of this document. -.. _testing: - -Testing -------- +## Testing You should test your changes locally before submitting a pull request to make sure they work correctly & don't break anything. @@ -93,129 +87,120 @@ to make sure they work correctly & don't break anything. Ideally, you should also write unit tests for new features. See the tests folder in this repo for current tests. -Testing Code Changes -^^^^^^^^^^^^^^^^^^^^ +### Testing Code Changes First, run the below command to run our linting tools automatically. This will run Mypy and Ruff against Arcade. The first run of this may take some as MyPy will not have any caches built up. Sub-sequent runs will be much faster. -.. code-block:: shell - - python make.py lint +```bash +python make.py lint +``` If you want to run either of these tools individually, you can do -.. code-block:: shell - - python make.py ruff +```bash +python make.py ruff +``` or -.. code-block:: shell - - python make.py mypy +```bash +python make.py mypy +``` Now you run the framework's unit tests with the following command: -.. code-block:: shell - - python make.py test +```bash +python make.py test +``` -Building & Testing Documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Building & Testing Documentation -Automatic Rebuild with Live Reload -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#### Automatic Rebuild with Live Reload You can build & preview documentation locally using the following steps. Run the doc build to build the web page files, and host a webserver to preview: -.. code-block:: shell +```bash +python make.py serve +``` - python make.py serve +You can now open http://localhost:8000 in your browser to preview the docs. -You can now open `http://localhost:8000 `_ in your browser to preview the docs. - -The ``doc/build/html`` directory will contain the generated website files. When you change source files, +The `doc/build/html` directory will contain the generated website files. When you change source files, it will automatically regenerate, and browser tabs will automatically refresh to show your updates. If you suspect the automatic rebuilds are failing to detect changes, you can run a simpler one-time build using the following instructions. -.. _how-to-compile: - -One-time build -~~~~~~~~~~~~~~ +#### One-time build Run the doc build to build the web page files: -.. code-block:: shell +```bash +python make.py html +``` - python make.py html - -The ``doc/build/html`` directory will contain the generated website files. +The `doc/build/html` directory will contain the generated website files. Start a local web server to preview the doc: -.. code-block:: shell - - python -m http.server -d doc/build/html +```bash +python -m http.server -d doc/build/html +``` -You can now open `http://localhost:8000 `_ in your browser to preview the doc. +You can now open http://localhost:8000 in your browser to preview the doc. Be sure to re-run build & refresh to update after making changes! -Optional: Improve Ergonomics on Mac and Linux ---------------------------------------------- +## Optional: Improve Ergonomics on Mac and Linux -make.py shorthand -^^^^^^^^^^^^^^^^^ +### make.py shorthand On Mac & Linux, you can run the make script as ``./make.py`` instead of ``python make.py``. For example, this command: -.. code-block:: shell - - python make.py lint +```bash +python make.py lint +``` can now be run this way: -.. code-block:: shell - - ./make.py lint +```bash +./make.py lint +``` -Enable Shell Completions -^^^^^^^^^^^^^^^^^^^^^^^^ +### Enable Shell Completions On Mac & Linux, you can enable tab completion for commands on the following supported shells: -* ``bash`` (the most common default shell) -* ``zsh`` -* ``fish`` -* ``powershell`` -* ``powersh`` +* `bash` (the most common default shell) +* `zsh` +* `fish` +* `powershell` +* `powersh` For example, if you have typed the following... -.. code-block:: shell - - ./make.py h +```bash +./make.py h +``` Tab completion would allow you to press tab to auto-complete the command: -.. code-block:: shell - - ./make.py html +```bash +./make.py html +``` Note that this may interfere if you work on other projects that also have a `make.py` file. To enable this feature, most users can follow these steps: -1. Run ``./make.py whichshell`` to find out what your default shell is -2. If it is one of the supported shells, run ``./make.py --install-completion $(basename "$SHELL")`` +1. Run `./make.py whichshell` to find out what your default shell is +2. If it is one of the supported shells, run `./make.py --install-completion $(basename "$SHELL")` 3. Restart your terminal If your default shell is not the shell you prefer using for arcade development, diff --git a/README.rst b/README.md similarity index 59% rename from README.rst rename to README.md index 9736ac892..4487aa030 100644 --- a/README.rst +++ b/README.md @@ -1,5 +1,4 @@ -Welcome to The Arcade Library! -============================== +# Welcome to The Arcade Library! Arcade is an easy-to-learn Python library for creating 2D video games. It is ideal for beginning programmers, or programmers who want to create @@ -7,25 +6,16 @@ It is ideal for beginning programmers, or programmers who want to create Arcade is built on top of Pyglet and OpenGL. -.. image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat) - :target: http://makeapullrequest.com - :alt: Pull Requests Welcome +[Pull Requests Welcome](http://makeapullrequest.com) +[First Timers Friendly](http://www.firsttimersonly.com/) -.. image:: https://img.shields.io/badge/first--timers--only-friendly-blue.svg - :alt: first-timers-only Friendly - :target: http://www.firsttimersonly.com/ +![PyPI - Downloads](https://img.shields.io/pypi/dm/arcade) -.. image:: https://img.shields.io/pypi/dm/arcade - :alt: PyPI - Downloads +![GitHub Commit Activity](https://img.shields.io/github/commit-activity/m/pythonarcade/arcade) -.. image:: https://img.shields.io/github/commit-activity/m/pythonarcade/arcade - :alt: GitHub commit activity +![MIT License](https://img.shields.io/pypi/l/arcade) -.. image:: https://img.shields.io/pypi/l/arcade - :alt: PyPI - License - -Documentation -------------- +## Documentation * For full documentation see https://api.arcade.academy * For installation: https://api.arcade.academy/en/latest/install/index.html @@ -34,16 +24,13 @@ Documentation * Learn Arcade AND how to program: https://learn.arcade.academy * Release notes: https://api.arcade.academy/en/latest/development/release_notes.html -Games Using Arcade ------------------- +## Games Using Arcade See: https://api.arcade.academy/en/latest/sample_games.html -Citation --------- - -.. code-block:: txt +## Citation +``` @Online{PythonArcade, author = {Paul Vincent Craven}, title = {Easy to use Python library for creating 2D arcade games.}, @@ -53,8 +40,8 @@ Citation howpublished = {\url{https://github.com/pythonarcade/arcade}}, commit = {} } +``` -Contact the Maintainer ----------------------- +## Contact the Maintainer paul@cravenfamily.com From 27cc48ae2ac2437616e96da3beddd023c7e5f276 Mon Sep 17 00:00:00 2001 From: Darren Eberly Date: Tue, 12 Dec 2023 01:22:01 -0500 Subject: [PATCH 2/4] Fix README link in pyproject.toml --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index b72c7e91a..60b8b3c6f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "arcade" description = "Arcade Game Development Library" -readme = "README.rst" +readme = "README.md" authors = [ {name="Paul Vincent Craven", email="paul@cravenfamily.com"} ] From 7c6f865c991efe0ec61c1dd03816329f97d0ffcd Mon Sep 17 00:00:00 2001 From: Darren Eberly Date: Sun, 25 Feb 2024 01:14:21 -0500 Subject: [PATCH 3/4] Update references to CONTRIBUTING.rst --- doc/contributing_guide/index.rst | 9 ++++++++- make.py | 8 ++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/contributing_guide/index.rst b/doc/contributing_guide/index.rst index 5c9a941bf..766cc5dd7 100644 --- a/doc/contributing_guide/index.rst +++ b/doc/contributing_guide/index.rst @@ -1,4 +1,11 @@ .. _cg_index_quickstart: -.. include:: ../../CONTRIBUTING.rst +Contributing To Arcade +====================== + +Arcade is managed and developed through our `Github Repository`_. For more information about how to get started with +contributing to Arcade, please visit the `Github Contributing Guide`_. + +.. _Github Repository: https://github.com/pythonarcade/arcade +.. _Github Contributing Guide: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md \ No newline at end of file diff --git a/make.py b/make.py index b663d1bb3..26f438f2d 100755 --- a/make.py +++ b/make.py @@ -8,7 +8,7 @@ For help, see the following: -* CONTRIBUTING.rst +* CONTRIBUTING.md * The output of python make.py --help """ import os @@ -76,7 +76,7 @@ def _resolve(p: PathLike, strict: bool = False) -> Path: not_found = [binary for binary in binaries if which(binary) is None] if not_found: print("Command-line tools not found: " + ', '.join(not_found)) - print("Did you forget to install them with `pip`? See CONTRIBUTING.rst file for instructions.") + print("Did you forget to install them with `pip`? See CONTRIBUTING.md file for instructions.") exit(1) for library in libraries: def find(library): @@ -87,7 +87,7 @@ def find(library): not_found = [library for library in libraries if not find(library)] if not_found: print("Python dependencies not found: " + ', '.join(not_found)) - print("Did you forget to install them with `pip`? See CONTRIBUTING.rst file for instructions.") + print("Did you forget to install them with `pip`? See CONTRIBUTING.md file for instructions.") exit(1) @@ -484,7 +484,7 @@ def whichshell(): if shell_name in SHELLS_WITH_AUTOCOMPLETE: print("This shell is known to support tab-completion!") - print("See CONTRIBUTING.rst for more information on how to enable it.") + print("See CONTRIBUTING.md for more information on how to enable it.") if __name__ == "__main__": From 06d000a699c7f0ba1dac670a330c492c239bedfc Mon Sep 17 00:00:00 2001 From: Darren Eberly Date: Sun, 25 Feb 2024 01:27:03 -0500 Subject: [PATCH 4/4] Update docs(remove unnecessary pages, consolidate on GitHub as source of truth for contributing guide) --- .../directory_structure.rst | 37 --------------- doc/contributing_guide/how_to_contribute.rst | 45 ------------------- .../how_to_submit_changes.rst | 25 ----------- doc/contributing_guide/index.rst | 25 ++++++++--- doc/index.rst | 3 -- 5 files changed, 19 insertions(+), 116 deletions(-) delete mode 100644 doc/contributing_guide/directory_structure.rst delete mode 100644 doc/contributing_guide/how_to_contribute.rst delete mode 100644 doc/contributing_guide/how_to_submit_changes.rst diff --git a/doc/contributing_guide/directory_structure.rst b/doc/contributing_guide/directory_structure.rst deleted file mode 100644 index dbec906ee..000000000 --- a/doc/contributing_guide/directory_structure.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _directory-structure: - -Directory Structure -=================== - -+------------------------+----------------------------------------------------+ -| Directory | Description | -+========================+====================================================+ -| \\arcade | Source code for the arcade library. | -| | including various sub-modules | -+------------------------+----------------------------------------------------+ -| \\arcade\examples | Example code showing how to use Arcade. | -+------------------------+----------------------------------------------------+ -| \\arcade\experimental | Experimental features and more advanced examples | -+------------------------+----------------------------------------------------+ -| \\tests | Unit tests. Most unit tests are part of the | -| | docstrings. | -+------------------------+----------------------------------------------------+ -| \\doc | Arcade documentation. Note that API documentation | -| | is in docstrings along with the source. | -+------------------------+----------------------------------------------------+ -| \\doc\\tutorials | Tutorial pages and code | -+------------------------+----------------------------------------------------+ -| \\doc\\\images | Images used in the documentation. | -+------------------------+----------------------------------------------------+ -| \\doc\\build\\html | After making the documentation, all the HTML code | -| | goes here. Look at this in a web browser to see | -| | what the documentation will look like. | -+------------------------+----------------------------------------------------+ -| \\build | All built code from the compile script goes | -| | here. | -+------------------------+----------------------------------------------------+ -| \\dist | Distributable Python wheels go here after the | -| | build script has run. | -+------------------------+----------------------------------------------------+ - -Also see :ref:`how-to-compile`. diff --git a/doc/contributing_guide/how_to_contribute.rst b/doc/contributing_guide/how_to_contribute.rst deleted file mode 100644 index 59ede58b8..000000000 --- a/doc/contributing_guide/how_to_contribute.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _how-to-contribute: - -Ways to Contribute -================== - -We would love to have you contribute to the project! There are several -ways that you can do so. - -How to contribute without coding -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Community** - Post your projects, code, screen-shots, and discuss the Arcade library on the `Python Arcade SubReddit`_. -* Try coding your own animations and games. Write down notes on anything that - is difficult to implement or understand about the library. -* **Suggest improvements** - Post bugs and enhancement requests at the `Github Issue List`_. - -How to contribute code -^^^^^^^^^^^^^^^^^^^^^^ - -First, take some time to understand the project layout: - -* :ref:`directory-structure` -* :ref:`how-to-compile` -* :ref:`how-to-submit-changes` - - -Then, perform the following steps: - -#. Make sure you have Python 3.9+ installed rather than 3.8+ to meet - dev tool requirements. -#. Make a virtual environment. -#. Run `pip install -e .[dev]` to perform a dev install. - - -Afterwards, you can improve these parts of the project: - -* **Document** - Edit the reStructuredText_ and docstrings_ to make the Arcade - documentation better. -* **Test** - Improve the unit testing. -* **Code** - Contribute bug fixes and enhancements to the code. - -.. _Python Arcade SubReddit: https://www.reddit.com/r/pythonarcade -.. _Github Issue List: https://github.com/pythonarcade/arcade/issues -.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html -.. _docstrings: http://www.pythonforbeginners.com/basics/python-docstrings diff --git a/doc/contributing_guide/how_to_submit_changes.rst b/doc/contributing_guide/how_to_submit_changes.rst deleted file mode 100644 index 0aa351d00..000000000 --- a/doc/contributing_guide/how_to_submit_changes.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _how-to-submit-changes: - -How to Submit Changes -===================== - -First, you should open up an issue or enhancement request on -the `Github Issue List`_. - -Next, `create your own fork`_ of the Arcade library. -The Arcade library is at: - -https://github.com/pythonarcade/arcade - -Follow the :ref:`how-to-compile` on how to build the code. - -You can submit changes with a "pull request." With a pull request you ask -that another repository (in this case the Arcade library) "pull" your -changes into the main code base. - -If you aren't familiar with how to do pull requests, the -`Stack Overflow discussion on pull requests`_ is good. - -.. _Stack Overflow discussion on pull requests: http://stackoverflow.com/questions/14680711/how-to-do-a-github-pull-request -.. _Github Issue List: https://github.com/pythonarcade/arcade/issues -.. _create your own fork: http://stackoverflow.com/questions/6286571/are-git-forks-actually-git-clones/6286877#6286877 diff --git a/doc/contributing_guide/index.rst b/doc/contributing_guide/index.rst index 766cc5dd7..262061ccf 100644 --- a/doc/contributing_guide/index.rst +++ b/doc/contributing_guide/index.rst @@ -1,11 +1,24 @@ - -.. _cg_index_quickstart: +.. _how-to-contribute: Contributing To Arcade ====================== -Arcade is managed and developed through our `Github Repository`_. For more information about how to get started with -contributing to Arcade, please visit the `Github Contributing Guide`_. +We would love to have you contribute to the project! There are several +ways that you can do so. + +How to contribute without coding +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Community** - Post your projects, code, screen-shots, and discuss the Arcade library on the `Python Arcade SubReddit`_. +* Try coding your own animations and games. Write down notes on anything that + is difficult to implement or understand about the library. +* **Suggest improvements** - Post bugs and enhancement requests at the `Github Issue List`_. + +How to contribute code +^^^^^^^^^^^^^^^^^^^^^^ + +If you are interested in contributing code, please check out the `Github Contributing Guide`_ -.. _Github Repository: https://github.com/pythonarcade/arcade -.. _Github Contributing Guide: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md \ No newline at end of file +.. _Python Arcade SubReddit: https://www.reddit.com/r/pythonarcade +.. _Github Issue List: https://github.com/pythonarcade/arcade/issues +.. _Github Contributing Guide: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md diff --git a/doc/index.rst b/doc/index.rst index fbf928583..49929c5d3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -143,10 +143,7 @@ The Python Arcade Library :maxdepth: 1 :caption: Contributing - contributing_guide/how_to_contribute contributing_guide/index - contributing_guide/directory_structure - contributing_guide/how_to_submit_changes contributing_guide/release_checklist .. image:: images/social.svg