bunch of small improvements

Author: JosephBARBIERDARNAL

_quarto.yml

@@ -4,9 +4,6 @@ project:
   preview:
     port: 4000
 
-website:
-  google-analytics: "G-XXXXXXXX"
-
 book:
   title: "Python Packaging Essentials"
   subtitle: "Practical guide that walks you through creating, organizing, testing, and publishing Python packages."
@@ -42,7 +39,8 @@ format:
     number-depth: 1
     css: styles.css
     theme:
-      - cosmo
-      - brand
+      light:
+        - cosmo
+        - brand
   pdf:
     documentclass: scrreprt

blog/create-a-package/handling-dependencies.qmd

@@ -4,7 +4,7 @@ title: "Handling dependencies"
 
 Dependencies are the external Python packages your code needs in order to work, such as `requests`, `numpy`, or `pandas`.
 
-Here we'll focus on using [uv](https://docs.astral.sh/uv/){target="_blank"} to handle dependencies, as it's currently the best tool for this out there (it's fast and fairly easy to use, especially if you know `pip`).
+Here we'll focus on using [uv](https://docs.astral.sh/uv/){target="_blank"} to handle dependencies, as it's currently the best tool for this out there (it's fast and fairly easy to use, especially if you know `pip` or other package manager like `Cargo`.).
 
 ## Specify dependencies
 
@@ -21,7 +21,7 @@ def normalize(array):
 
 When people want to use our function, they **need** to have `numpy` installed for it to work, otherwise it will raise a `ModuleNotFoundError` on their machine.
 
-So in order to ensure is `numpy` installed, we set `numpy` as a dependency of our package. This means that every time someone install our package, they will also install `numpy`.
+So in order to ensure that this does not happen, we need to tell Python to also install `numpy` when installing our package. In practice, we say that we set `numpy` as a **dependency** of our package. This means that every time someone install our package, they will also install `numpy`.
 
 The dependencies of a package are listed in the `pyproject.toml` file. If you don't know what that is, check out [organizing a package](./organize-a-package.html).
 
@@ -63,7 +63,7 @@ dependencies = [
 
 :::
 
-If we add other dependencies, they will be added to the `dependencies` list.
+From now on, numpy will also be installed when users install our package. If we add other dependencies, they will be added to the "dependencies" list: we can have as many dependencies as we want, but we want to avoid that.
 
 ## Avoiding dependencies
 
@@ -125,7 +125,7 @@ uv pip install numpy
 
 :::
 
-Note that for each of those, the package resolver will always try to install the latest version it can depending on the other dependencies. If a package requires `numpy<=2.1.0`, other packages **must** include `numpy` `2.1.0` for it to work.
+Note that for each of those, the package manager will always try to install the latest version it can depending on the other dependencies. If a package requires `numpy<=2.1.0`, other packages **must** include `numpy` `2.1.0` for it to work.
 
 At this point, you might ask, **how do I know** which versions of each dependencies are required for my package? Well, as far as I know, there is no easy answer to this, but there are ways to ensure you don't get unexpected behaviors.
 
@@ -146,7 +146,7 @@ You have to test that your code works as expected on those versions. The best wa
 
 ### ... and be convenient
 
-> Dependening on whether you're planning on distributing your package (e.g., put it on PyPI and allow other people to install it) or not, you might want to do different things here. We'll assume you want to distribute it at the end.
+> Depending on whether you're planning on distributing your package (e.g., put it on PyPI and allow other people to install it) or not, you might want to do different things here. We'll assume you want to distribute it at the end.
 
 When your package goaled is to be installed by other people, you want to be convenient. By that I mean **not being too restrictive**.
 
@@ -250,6 +250,10 @@ def read_file(filename):
             )
 ```
 
+::: {.callout-important}
+It is **required** here to place `import` inside the function, because otherwise a `ModuleNotFoundError` error will be generated on the user's machine, even when importing a function with only optional dependencies..
+:::
+
 This will give your users a **clear and meaningful error message** that they can resolve very quickly. This kind of thing exist for the same reason we're talking about in this article: trying to minimize the number of dependencies (especially the unused ones!).
 
 In order to add package to your optional dependencies, you can run:
@@ -319,3 +323,4 @@ uv sync --all-groups
 ```
 
 
+The next section is about [code quality](../code-quality/) in your package.

blog/create-a-package/introduction-to-packaging.qmd

@@ -24,6 +24,8 @@ from my_package import something
 
 Without it, Python treats the directory `my_package/` as a regular directory, **not something it can import from**.
 
+> Note that this is not always true, but it does not matter here. See [namespace packages](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/){target="_blank"}.
+
 
 
 ## Package vs Module vs Library
@@ -34,7 +36,7 @@ These terms get thrown around a lot. Here's the quick breakdown:
 - **Package**: A directory with an `__init__.py`, possibly containing multiple modules (e.g., multiple files)
 - **Library**: A more general programming term and refers to a bundle of code that can be used ([source](https://www.reddit.com/r/Python/comments/weycrc/comment/iiqy6fi/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button){target="_blank"})
 
-Library and package most of the time refer to the same thing. All packages are libraries, the opposite is not true. For the sake of simplicity, it's ok to consider them "equivalent", even though we're are mostly interested in packages in practice.
+Library and package most of the time refer to the same thing. All packages are libraries, the opposite is not true. For the sake of simplicity, **it's ok to consider them "equivalent"**, even though we're are mostly interested in packages in practice.
 
 Now, let's create the smallest Python package possible.
 
@@ -105,6 +107,8 @@ def say_hello(name):
    print(message)
 ```
 
+Here we define the main function of our package.
+
 ### `__init__.py`
 
 ```{.python filename="package_name/__init__.py"}
@@ -113,13 +117,14 @@ from .my_module import say_hello
 __all__ = ["say_hello"]
 ```
 
+Without the `__init__.py` file, we wouldn't be able to use `from my_package import say_hello` and would have to use `from my_package.my_module import say_hello`, which isn't the best syntax (but sometimes it can be!).
 :::
 
 ## Use our package
 
-Now, how do we use our package, from a user point of view?
+Untile now, we were from the package developer side, but how do we use our package, from a user point of view?
 
-For this, you'll need to have [uv](https://docs.astral.sh/uv/){target="_blank"} installed.
+For this, you'll need to have [uv](https://docs.astral.sh/uv/){target="_blank"} installed (not mandatory, but it makes things much easier).
 
 Then we'll need to run a command in our terminal at `Desktop/my_package/`:
 
@@ -144,4 +149,6 @@ say_hello("Julia")
 > Hello Julia
 
 
-And now we have a fully functional Python package! This is just the beginning, but this is an important fondation to have for what's coming next.
+And now we have a **fully functional Python package**! This is just the beginning, but this is an important fondation to have for what's coming next.
+
+Next, we need to [organize the package](./organize-a-package.html), particularly to get an overview of all the files we need (most of which are not Python files).

blog/create-a-package/organize-a-package.qmd

@@ -38,13 +38,15 @@ __all__ = ["count_sunflowers"]
 
 ## Add main Python project files
 
-Next, we need to create a few essential files at the root of the project.
+Next, we need to create a few essential files at the root of the project. As you can see, most of them are not Python files, but they are still very important.
 
 ::: {.panel-tabset}
 
 ### `pyproject.toml`
 
-All the package metadata. It will contain a lot of useful information when we want to distribute this PyPI package so that everyone can install it easily. Don't worry too much about all of its content.
+All the metadata for the package. This is essentially your package's identifier, which contains a lot of useful information when we want to distribute a package so that anyone can easily install it.
+
+For example, it contains information about the license (what are users allowed to do with our package?), dependencies (what packages does our package need?), and lots of other metadata about the package (author(s), version, description, etc.).
 
 Here is a simple version of this file:
 
@@ -207,7 +209,7 @@ sunflower/
 
 ## Add an internal function
 
-When creating a package, it is very practical to create functions that we will use internally: inside the package itself.
+When creating a package, it is very useful to create functions that we will use internally: within the package itself, but which are not intended for users of the package.
 
 If we go back to our previous example, we might want to have a separate function that takes a string and cleans it up by removing non-text characters and putting it in lower case. Let's name this function `_clean_string()` and place it in a new file: `other_module.py`.
 
@@ -263,3 +265,7 @@ sunflower/
 ├── sandbox.py
 └── pyproject.toml
 ```
+
+We now have a basic but fairly robust file organization in our package. Now, if we want to continue improving our package, everything will happen directly in the `sunflower/sunflower` directory.
+
+The next step is to [handle dependencies](./handling-dependencies.html), i.e., identify and specify the packages needed to use our package.

styles.css

@@ -38,12 +38,8 @@ a:not(.sidebar a):not(header a):not(.nav-item a):not(.nav-page a)::after {
   left: 0;
   bottom: 0;
   width: 100%;
-  height: 3px;
+  height: 2px;
   background-color: var(--primary-color);
   transition: all 0.3s ease;
   z-index: -1; /* goes behind text */
 }
-
-a:not(.sidebar a):not(header a):not(.nav-item a):not(.nav-page a):hover::after {
-  height: 80%; /* increased thickness */
-}