From 0a5ec23382f85e3f83ad78cd09a46ac0ed3627c8 Mon Sep 17 00:00:00 2001 From: Catalin Date: Thu, 1 Aug 2024 19:58:12 +0300 Subject: [PATCH] HDX-9928 add documentation and ruff dev dependency --- ckanext-hdx_theme/docs/README.rst | 6 ++ .../docs/code_quality/linter.rst | 60 +++++++++++++++++++ .../docs/code_quality/type_checker.rst | 28 +++++++++ dev-requirements.in | 1 + 4 files changed, 95 insertions(+) create mode 100644 ckanext-hdx_theme/docs/code_quality/linter.rst create mode 100644 ckanext-hdx_theme/docs/code_quality/type_checker.rst diff --git a/ckanext-hdx_theme/docs/README.rst b/ckanext-hdx_theme/docs/README.rst index 927b885e88..82062d1098 100644 --- a/ckanext-hdx_theme/docs/README.rst +++ b/ckanext-hdx_theme/docs/README.rst @@ -40,3 +40,9 @@ Adding a new field to dataset. Please note that doesn't necessarily mean storing HOW TO DOWNLOAD FILES/RESOURCES FROM HDX -------------- Information about how to download the files from HDX can be found here `Download Files from HDX `_ + +CODE QUALITY +++++++++++++ +Information about configuring the linter (Ruff) can be found here: `Linter Configuration `_. + +Information about configuring the type(s) checker can be found here: `Type Checker Configuration `_. diff --git a/ckanext-hdx_theme/docs/code_quality/linter.rst b/ckanext-hdx_theme/docs/code_quality/linter.rst new file mode 100644 index 0000000000..7f3d512b82 --- /dev/null +++ b/ckanext-hdx_theme/docs/code_quality/linter.rst @@ -0,0 +1,60 @@ +Code Quality +============ + +Linter Configuration +++++++++++++++++++++ +This section outlines how to configure the linter, Ruff, for your local development environment in PyCharm. + +Installing Ruff Linter +---------------------- + +Since we utilize CKAN within a Docker container, you'll need Ruff installed locally on your development machine. + +Ruff is available as ``ruff`` on PyPI: + +:: + + pip install ruff + +Starting with version ``0.5.0``, Ruff can be installed using their standalone installers: + +:: + + # On macOS and Linux. + curl -LsSf https://astral.sh/ruff/install.sh | sh + + # On Windows. + powershell -c "irm https://astral.sh/ruff/install.ps1 | iex" + + # For a specific version. + curl -LsSf https://astral.sh/ruff/0.5.0/install.sh | sh + powershell -c "irm https://astral.sh/ruff/0.5.0/install.ps1 | iex" + +For **macOS Homebrew** and **Linuxbrew** users, Ruff is also available as ``ruff`` on Homebrew: + +:: + + brew install ruff + +Enabling Ruff Extension in PyCharm +---------------------------------- + +1. Open `File` > `Settings` (or `Preferences` on macOS) > `Plugins`. +2. Ensure the ``Marketplace`` tab is active. +3. Search for and install the ``Ruff`` extension. + +Configuring Ruff Extension in PyCharm +------------------------------------- + +1. Go to `File` > `Settings` (or `Preferences` on macOS) > `Tools` > `Ruff`. +2. Verify that only the following options are checked: + + * ``Run ruff when Reformat Code`` + * ``Show Rule Code on inspection message`` + +3. Set the Ruff executable path in the ``Global`` section if it is not already set. + +Ruff Configuration File +----------------------- + +The configuration for Ruff can be found in the project root directory in the ``pyproject.toml`` file. diff --git a/ckanext-hdx_theme/docs/code_quality/type_checker.rst b/ckanext-hdx_theme/docs/code_quality/type_checker.rst new file mode 100644 index 0000000000..6a7fd2abf3 --- /dev/null +++ b/ckanext-hdx_theme/docs/code_quality/type_checker.rst @@ -0,0 +1,28 @@ +Code Quality +============ + +Type Checker Configuration +++++++++++++++++++++++++++ +This section details enabling and configuring type checking within PyCharm. + +Enabling Type Checking in PyCharm +--------------------------------- + +1. Go to `File` > `Settings` (or `Preferences` on macOS) > `Editor` > `Inspections`. +2. Enable the following inspections: + + * Python > ``Incorrect type`` + * Python > ``Missing type hinting for function definition`` + +3. For the ``Missing type hinting for function definition`` inspection, click on it and uncheck the ``Only when types are known`` option. + +Optional Configuration +---------------------- + +1. You can adjust the severity level to ``Warning`` or ``Error`` for both inspections by clicking on them and selecting the desired level under the ``Severity`` option. + +Manually Running Type Checking Inspections +------------------------------------------ + +1. Go to `Code` > `Inspect Code`. +2. Choose the scope (e.g., `Current File` or `Whole Project`). diff --git a/dev-requirements.in b/dev-requirements.in index a3edef4ef6..78bc41c3af 100644 --- a/dev-requirements.in +++ b/dev-requirements.in @@ -26,3 +26,4 @@ pytest-rerunfailures==10.2 towncrier==22.8.0 moto==2.3.2 +ruff==0.5.5