diff --git a/getting_started/git_repo.rst b/getting_started/git_repo.rst index f34a3bd..c35632f 100644 --- a/getting_started/git_repo.rst +++ b/getting_started/git_repo.rst @@ -121,8 +121,8 @@ You should see a message similar to: :: - kristian@mylaptop:~/projects$ git clone git@github.com:krother/snake.git - Cloning into 'snake'... + kristian@mylaptop:~/projects$ git clone git@github.com:krother/dungeon_explorer.git + Cloning into 'dungeon_explorer'... remote: Enumerating objects: 5, done. remote: Counting objects: 100% (5/5), done. remote: Compressing objects: 100% (4/4), done. @@ -133,7 +133,7 @@ There also should be a new folder: :: - kristian@mylaptop:~/projects$ ls -la snake + kristian@mylaptop:~/projects$ ls -la dungeon_explorer total 24 drwxrwxr-x 3 kristian kristian 4096 Mai 28 11:33 . drwxrwxr-x 50 kristian kristian 4096 Mai 28 11:33 .. @@ -151,11 +151,11 @@ like this: :: - cd snake/ + cd dungeon_explorer/ cp ~/Desktop/prototype.py . git status git add prototype.py - git commit -m "add a snake prototype" + git commit -m "add a dungeon_explorer prototype" git push To exectute ``git push``, you may need to `Add SSH keys to your GitHub diff --git a/getting_started/structure.rst b/getting_started/structure.rst index 6f3464e..685f516 100644 --- a/getting_started/structure.rst +++ b/getting_started/structure.rst @@ -10,16 +10,16 @@ Step 1: A package folder First, you need a place for the package you want to write. A **Python package** is simply a folder that contains ``.py`` files. Create a -folder ``snake`` inside your repository. On the bash terminal, you would +folder ``dungeon_explorer`` inside your repository. On the bash terminal, you would use :: - mkdir snake + mkdir dungeon_explorer -If your git repository is also called ``snake``, you may want to rename -your project folder to something else like ``snake_project``, -``snake_repo`` or similar. If you have two folders calles ``snake`` +If your project folder (with the git repo) is also called ``dungeon_explorer``, +you may want to rename the project folder to something else like ``dungeon_project`` or similar. +Having two folders called ``dungeon_explorer`` inside each other could lead to strange import bugs later -------------- @@ -41,12 +41,12 @@ Step 3: Create a Python module You may want to create a Python module (a ``.py`` file) to make sure everything is set up correctly. Create a file ``game.py`` inside the -``snake/`` folder. Add a placeholder function to it: +``dungeon_explorer/`` folder. Add a placeholder function to it: :: - def play_snake(): - print('this is a snake game') + def play(): + print('this is the Dungeon Explorer game') Now start Python in your main project folder (above the package) through the terminal. **It is important that you start Python in your project @@ -55,9 +55,9 @@ code that you want to get running is: :: - from snake.game import play_snake + from dungeon_explorer.game import play - play_snake() + play() You should see the message from the print statement. @@ -66,22 +66,22 @@ You should see the message from the print statement. Step 4: main Python file ~~~~~~~~~~~~~~~~~~~~~~~~ -Importing the ``play_snake()`` function to play the game is a bit +Importing the ``play()`` function to play the game is a bit inconvenient. Let’s create a shortcut. Create a file named ``__main__.py`` (with double underscores on both ends) in the package folder that contains the following code: :: - from game import play_snake + from game import play - play_snake() + play() Now it should be possible to start the game by typing: :: - python snake + python dungeon_explorer -------------- @@ -95,7 +95,7 @@ At this point, your project folder should contain: LICENSE prototype.py README.md - snake/ + dungeon_explorer/ game.py __main__.py tests/ diff --git a/getting_started/virtualenv.rst b/getting_started/virtualenv.rst index 6377538..fbbe5e7 100644 --- a/getting_started/virtualenv.rst +++ b/getting_started/virtualenv.rst @@ -42,12 +42,12 @@ Once the installer finishes and you open a new terminal, you should see This means you are in an virtual environment called *“base”*. -Let’s create a new one for a project called **snake**, specifying a +Let’s create a new one for a project called **dungeon_explorer**, specifying a Python version: :: - conda create -n snake python=3.11 + conda create -n dungeon_explorer python=3.11 Behind the scenes **conda** creates a new subdirectory. This is where libraries for your project will be stored. There are also scripts to @@ -62,9 +62,9 @@ To start working with your project, type: :: - conda activate snake + conda activate dungeon_explorer -You should see a *(snake)* appearing at your prompt. Now, whenever you +You should see *(dungeon_explorer)* appearing before your prompt. Now, whenever you use *pip* to install something, it will be installed only for *myproject*. @@ -74,11 +74,12 @@ Now check which libraries you have installed: pip freeze -You can install additional libraries with ``pip`` or ``conda``: +You can install additional libraries with ``pip`` or ``conda``. +For instance, you need to install OpenCV even if you already installed it in your base environment: :: - conda install pandas + conda install opencv-python When you want to switch back to the base environment, type: diff --git a/quality/packaging.rst b/quality/packaging.rst index e4640e6..dbc96c7 100644 --- a/quality/packaging.rst +++ b/quality/packaging.rst @@ -10,13 +10,13 @@ Assume your project folder contains: :: - snake_game/ - module folder you want to import - tests/ - the test code for pytest - .git/ - the commit history (managed by git) - README.md - documentation - LICENSE - legal info - setup.py - used by pip (see below) - .gitignore - choose one on Github + dungeon_explorer/ - module folder you want to import + tests/ - the test code for pytest + .git/ - the commit history (managed by git) + README.md - documentation + LICENSE - legal info + setup.py - used by pip (see below) + .gitignore - choose one on Github The Project Folder ------------------ @@ -50,18 +50,16 @@ tells the installer what to install. You can use the following return open(os.path.join(os.path.dirname(__file__), "README.md")).read() setup( - name="snake_game", # snake is already taken on PyPi - version="0.0.1", # uses *semantic versioning* - description="a terminal-based snake game", + name="dungeon_explorer", # name used on PyPi + version="0.0.1", # uses *semantic versioning* + description="a simpl dungeon RPG", long_description=get_readme(), author="your_name", author_email="your@name.com", - packages=["snake_game"], # the name of the folder with .py modules + packages=["dungeon_explorer"], # the folder with .py modules url="https://github.com/...", license="MIT", classifiers=[ - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", @@ -97,12 +95,12 @@ you should be able to run from any other Python program: :: - import snake_game + import dungeon_explorer In other words, you don’t actually need to be in your project folder to use your program. This is super convenient! You can use your package -from anywhere as if it were an official library, like **pandas** or -**sklearn**. You should also see your package in the output of +from anywhere as if it were an official library, like **numpy** or +**pydantic**. You should also see your package in the output of ``pip list`` or ``pip freeze``. This method has the advantage that you can still edit your code, and the @@ -168,7 +166,7 @@ install it with :: - pip install snake_game + pip install dungeon_explorer you need to follow a few more steps. This is not difficult but a bit tedious. We recommend the official