From ad22d2580cc36f0a27060df1ae940dd5266e5b45 Mon Sep 17 00:00:00 2001 From: Lokesh Dhakal <9079364+aviranzerioniac@users.noreply.github.com> Date: Sun, 22 Nov 2020 16:22:12 +0100 Subject: [PATCH] Minor Polishes --- docs/writing/license.rst | 4 ++-- docs/writing/logging.rst | 10 +++++----- docs/writing/structure.rst | 13 ++++++------- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 0a74f54..820cc9a 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -6,8 +6,8 @@ Choosing a License .. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg -Your source publication *needs* a license. In the US, if no license is -specified, users have no legal right to download, modify, or distribute. +Your source publication *needs* a license. In the US, unless a license is +specified, users have no legal right to download, modify, or distribute the product. Furthermore, people can't contribute to your code unless you tell them what rules to play by. Choosing a license is complicated, so here are some pointers: diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst index b609dc7..b6110f7 100644 --- a/docs/writing/logging.rst +++ b/docs/writing/logging.rst @@ -10,7 +10,7 @@ The :mod:`logging` module has been a part of Python's Standard Library since version 2.3. It is succinctly described in :pep:`282`. The documentation is notoriously hard to read, except for the `basic logging tutorial`_. -As an alternative, `loguru `_ provides an approach to logging nearly as simple as using a simple ``print`` statement. +As an alternative, `loguru `_ provides an approach for logging, nearly as simple as using a simple ``print`` statement. Logging serves two purposes: @@ -59,7 +59,7 @@ using the ``__name__`` global variable: the :mod:`logging` module creates a hierarchy of loggers using dot notation, so using ``__name__`` ensures no name collisions. -Here is an example of best practice from the `requests source`_ -- place +Here is an example of the best practice from the `requests source`_ -- place this in your ``__init__.py``: .. code-block:: python @@ -83,7 +83,7 @@ application environment. There are at least three ways to configure a logger: - Using an INI-formatted file: - - **Pro**: possible to update configuration while running using the + - **Pro**: possible to update configuration while running, using the function :func:`logging.config.listen` to listen on a socket. - **Con**: less control (e.g. custom subclassed filters or loggers) than possible when configuring a logger in code. @@ -94,13 +94,13 @@ There are at least three ways to configure a logger: - **Con**: less control than when configuring a logger in code. - Using code: - **Pro**: complete control over the configuration. - - **Con**: modifications require a change to source code. + - **Con**: modifications require a change to the source code. Example Configuration via an INI File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Let us say the file is named ``logging_config.ini``. +Let us say that the file is named ``logging_config.ini``. More details for the file format are in the `logging configuration`_ section of the `logging tutorial`_. diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index bbbef47..7a73e36 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -18,7 +18,7 @@ the project? What features and functions can be grouped together and isolated? By answering questions like these you can begin to plan, in a broad sense, what your finished product will look like. -In this section we take a closer look at Python's module and import +In this section, we take a closer look at Python's modules and import systems as they are the central elements to enforcing structure in your project. We then discuss various perspectives on how to build code which can be extended and tested reliably. @@ -32,7 +32,7 @@ It's Important. ::::::::::::::: Just as Code Style, API Design, and Automation are essential for a -healthy development cycle, Repository structure is a crucial part of +healthy development cycle. Repository structure is a crucial part of your project's `architecture `__. @@ -54,8 +54,7 @@ documentation. Of course, first impressions aren't everything. You and your colleagues will spend countless hours working with this repository, eventually -becoming intimately familiar with every nook and cranny. The layout of -it is important. +becoming intimately familiar with every nook and cranny. The layout is important. Sample Repository ::::::::::::::::: @@ -126,7 +125,7 @@ If you aren't sure which license you should use for your project, check out `choosealicense.com `_. Of course, you are also free to publish code without a license, but this -would prevent many people from potentially using your code. +would prevent many people from potentially using or contributing to your code. Setup.py :::::::: @@ -157,8 +156,8 @@ should be placed at the root of the repository. It should specify the dependencies required to contribute to the project: testing, building, and generating documentation. -If your project has no development dependencies, or you prefer -development environment setup via ``setup.py``, this file may be +If your project has no development dependencies, or if you prefer +setting up a development environment via ``setup.py``, this file may be unnecessary. Documentation