From bf2b6944f07c6c4346ef9a9a51c0d77f7c07a4f7 Mon Sep 17 00:00:00 2001 From: Paul-Emmanuel Raoul Date: Thu, 20 Jun 2024 13:43:14 +0200 Subject: [PATCH 1/5] Add 'Development' section to documentation --- docs/development.rst | 31 +++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 32 insertions(+) create mode 100644 docs/development.rst diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..405fb94 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,31 @@ +=========== +Development +=========== + +Dropping support for deprecated Python versions +----------------------------------------------- + +When a Python version is officially deprecated, it needs to be removed from the +versions supported by this package. To do so, the following actions need to be taken: + +* In `setup.cfg`: + + * Remove the Python version from the classifiers. + * Update the minimum supported Python version in `python_requires`. + +* In `tox.ini`: + + * Remove the Python version from `tox.envlist`. + * Remove the Python version from `gh-actions.python`. + +* In `.github/workflows/test_and_publish.yml`: + + * Remove the Python version from the build matrix. + +* In the GitHub repository settings: + + * If necessary, update the required status checks in the branch protection + rules. + +The status of the Python versions can be found `here +`_. diff --git a/docs/index.rst b/docs/index.rst index a1a597f..1d2f9c2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ Faker Wi-Fi ESSID is a `Faker`_ provider for Wi-Fi ESSIDs. installation usage modules + development documentation .. _Faker: https://github.com/joke2k/faker/ From 8ffe4bbf215a4625d15545e7a5898bace5547c86 Mon Sep 17 00:00:00 2001 From: Paul-Emmanuel Raoul Date: Fri, 13 Dec 2024 15:51:12 +0100 Subject: [PATCH 2/5] Use dynamic copyright range in Sphinx doc --- docs/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 638be4e..e2884e4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,12 +16,14 @@ # pylint: skip-file +from datetime import datetime + from faker_wifi_essid import __version__ as VERSION # -- Project information ----------------------------------------------------- project = "Faker Wi-Fi ESSID" -copyright = "2022, Paul-Emmanuel Raoul" +copyright = f"2018-{datetime.now().year}, Paul-Emmanuel Raoul" author = "Paul-Emmanuel Raoul" # The full version, including alpha/beta/rc tags From 318f01f2b3e054c268652e0c4c304f28292df033 Mon Sep 17 00:00:00 2001 From: Paul-Emmanuel Raoul Date: Fri, 13 Dec 2024 15:56:25 +0100 Subject: [PATCH 3/5] Update instructions related to 'setup.cfg' This commit updates all references to 'setup.cfg' following its replacement with 'pyproject.toml' in commit 8e7b1a3. --- docs/development.rst | 5 ++--- docs/documentation.rst | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/development.rst b/docs/development.rst index 405fb94..581ba74 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -8,15 +8,14 @@ Dropping support for deprecated Python versions When a Python version is officially deprecated, it needs to be removed from the versions supported by this package. To do so, the following actions need to be taken: -* In `setup.cfg`: +* In `pyproject.toml`: * Remove the Python version from the classifiers. - * Update the minimum supported Python version in `python_requires`. + * Update the minimum supported Python version in `requires-python`. * In `tox.ini`: * Remove the Python version from `tox.envlist`. - * Remove the Python version from `gh-actions.python`. * In `.github/workflows/test_and_publish.yml`: diff --git a/docs/documentation.rst b/docs/documentation.rst index 4214ccd..14e59f2 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -8,8 +8,8 @@ folder. Install the dependencies ------------------------ -The dependencies required to build the documentation are defined in `setup.py` -as an optional dependency group called `docs`. +The dependencies required to build the documentation are defined in +`pyproject.toml` as an optional dependency group called `docs`. To install the dependencies in `docs`: From 82c1c95bc56c02a8fbb99b0ddad8646cb4bd2ea3 Mon Sep 17 00:00:00 2001 From: Paul-Emmanuel Raoul Date: Fri, 13 Dec 2024 16:17:38 +0100 Subject: [PATCH 4/5] Reorganise documentation pages --- docs/development.rst | 29 +++---------------- docs/{ => development}/documentation.rst | 0 .../drop-deprecated-py-versions.rst | 28 ++++++++++++++++++ docs/{ => development}/modules.rst | 2 +- .../modules/faker_wifi_essid.rst | 0 docs/index.rst | 3 +- 6 files changed, 34 insertions(+), 28 deletions(-) rename docs/{ => development}/documentation.rst (100%) create mode 100644 docs/development/drop-deprecated-py-versions.rst rename docs/{ => development}/modules.rst (100%) rename docs/{ => development}/modules/faker_wifi_essid.rst (100%) diff --git a/docs/development.rst b/docs/development.rst index 581ba74..deb0505 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -2,29 +2,8 @@ Development =========== -Dropping support for deprecated Python versions ------------------------------------------------ +.. toctree:: + :glob: + :maxdepth: 2 -When a Python version is officially deprecated, it needs to be removed from the -versions supported by this package. To do so, the following actions need to be taken: - -* In `pyproject.toml`: - - * Remove the Python version from the classifiers. - * Update the minimum supported Python version in `requires-python`. - -* In `tox.ini`: - - * Remove the Python version from `tox.envlist`. - -* In `.github/workflows/test_and_publish.yml`: - - * Remove the Python version from the build matrix. - -* In the GitHub repository settings: - - * If necessary, update the required status checks in the branch protection - rules. - -The status of the Python versions can be found `here -`_. + development/* diff --git a/docs/documentation.rst b/docs/development/documentation.rst similarity index 100% rename from docs/documentation.rst rename to docs/development/documentation.rst diff --git a/docs/development/drop-deprecated-py-versions.rst b/docs/development/drop-deprecated-py-versions.rst new file mode 100644 index 0000000..dce6934 --- /dev/null +++ b/docs/development/drop-deprecated-py-versions.rst @@ -0,0 +1,28 @@ +=============================================== +Dropping support for deprecated Python versions +=============================================== + +When a Python version is officially deprecated, it needs to be removed from the +versions supported by this package. To do so, the following actions need to be taken: + +* In `pyproject.toml`: + + * Remove the Python version from the classifiers. + * Update the minimum supported Python version in `requires-python`. + +* In `tox.ini`: + + * Remove the Python version from `tox.envlist`. + +* In `.github/workflows/test_and_publish.yml`: + + * Remove the Python version from the build matrix. + +* In the GitHub repository settings: + + * If necessary, update the required status checks in the branch protection + rules. + +The status of the Python versions can be found `here +`_. + diff --git a/docs/modules.rst b/docs/development/modules.rst similarity index 100% rename from docs/modules.rst rename to docs/development/modules.rst index 5cdee9b..5acb920 100644 --- a/docs/modules.rst +++ b/docs/development/modules.rst @@ -5,7 +5,7 @@ Modules The different modules of Faker Wi-Fi ESSID will be listed here. .. toctree:: - :maxdepth: 1 :glob: + :maxdepth: 1 modules/* diff --git a/docs/modules/faker_wifi_essid.rst b/docs/development/modules/faker_wifi_essid.rst similarity index 100% rename from docs/modules/faker_wifi_essid.rst rename to docs/development/modules/faker_wifi_essid.rst diff --git a/docs/index.rst b/docs/index.rst index 1d2f9c2..efdb788 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,11 +14,10 @@ Faker Wi-Fi ESSID is a `Faker`_ provider for Wi-Fi ESSIDs. .. toctree:: :caption: Contents + :maxdepth: 2 installation usage - modules development - documentation .. _Faker: https://github.com/joke2k/faker/ From ee9057e74c8129c8a364fb8fc6bb354667734545 Mon Sep 17 00:00:00 2001 From: Paul-Emmanuel Raoul Date: Fri, 13 Dec 2024 17:09:56 +0100 Subject: [PATCH 5/5] Update installation instructions --- docs/development/documentation.rst | 2 +- docs/installation.rst | 25 ++++++++++++++++++++----- 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/development/documentation.rst b/docs/development/documentation.rst index 14e59f2..6606f3c 100644 --- a/docs/development/documentation.rst +++ b/docs/development/documentation.rst @@ -15,7 +15,7 @@ To install the dependencies in `docs`: :: - pip3 install .[docs] + pip install .[docs] Build the documentation diff --git a/docs/installation.rst b/docs/installation.rst index 96f20a9..cbc5782 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,9 +5,22 @@ Installation From PyPI (recommended) ----------------------- -:: +To install Faker Wi-Fi ESSID from `PyPI`_ with pip: - pip3 install --upgrade faker-wifi-essid +.. code:: sh + + pip install --upgrade faker-wifi-essid + +However, as Faker Wi-Fi ESSID is a programming library (a `module `_ in Python parlance), it is most likely to be added as a dependency +to the `pyproject.toml` file of your project or its equivalent configuration +file: + +.. code:: toml + + dependencies = [ + "faker_wifi_essid", + ] From sources ------------ @@ -17,10 +30,12 @@ Faker Wi-Fi ESSID is packaged with `Setuptools`_. The default Git branch is `develop`. To install the latest stable version, you need to clone the `main` branch. -:: +.. code:: sh - git clone -b main git@github.com:SkypLabs/faker-wifi-essid.git + git clone -b main https://github.com/SkypLabs/faker-wifi-essid.git cd faker-wifi-essid - pip3 install . + pip install . +.. _Python Modules: https://docs.python.org/3/tutorial/modules.html +.. _PyPI: https://pypi.org/ .. _Setuptools: https://pypi.org/project/setuptools/