From 35cdd8dbae7687226db6ff043e99bc93e8b11aad Mon Sep 17 00:00:00 2001 From: Eduardo Leyva <75857767+TheRealVizard@users.noreply.github.com> Date: Sun, 17 Sep 2023 14:29:40 -0400 Subject: [PATCH] Updated Docs and workflows, bump packages version (#40) * Updated Docs and workflows, bump packages version * Updated test workflow --- .github/workflows/tests.yml | 14 +++--- docs/conf.py | 2 +- docs/usage.rst | 87 ++++++++++++++++++++++--------------- pyproject.toml | 11 ++--- 4 files changed, 66 insertions(+), 48 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 2efa997..6b4a098 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -1,28 +1,28 @@ name: Test on: - pull_request: - push: - branches: - - main + pull_request: + push: + branches: + - main jobs: run: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.10", "3.11"] - poetry-version: ["1.2.2"] + poetry-version: ["1.6.1"] steps: - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: - python-version: ${{ matrix.python-version }} + python-version: ${{ matrix.python-version }} - name: Install Dependencies uses: abatilo/actions-poetry@v2 with: - poetry-version: ${{ matrix.poetry-version }} + poetry-version: ${{ matrix.poetry-version }} - run: poetry install --with test - name: Generate coverage report run: poetry run pytest --cov=./ --cov-report=xml diff --git a/docs/conf.py b/docs/conf.py index d309f4f..50ee16a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,7 +18,7 @@ author = "Eduardo Leyva" copyright = f"{datetime.now().year}, {author}" -version = "0.4.1" +version = "0.6.0" extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"] diff --git a/docs/usage.rst b/docs/usage.rst index c865dda..67e9fbe 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,11 +1,11 @@ =============== -Getting started +Getting Started =============== -The test models +The Test Models *************** -For example purposes, we'll use a simplified book app. Here is our models. +For example purposes, we'll use a simplified book app. Here are our models. .. code-block:: python @@ -19,14 +19,13 @@ For example purposes, we'll use a simplified book app. Here is our models. def __str__(self): return self.name -Basic usage +Basic Usage *********** .. code-block:: python from django.shortcuts import render from django_table_sort.table import TableSort - from app.models import Person @@ -34,15 +33,16 @@ Basic usage table = TableSort(request, Person.objects.all()) return render(request, "template.html", context={"table": table}) -This is the basic usage of the table sort. You can use this to display Queryset and also list of items. +This is the basic usage of the table sort. You can use this to display a Queryset and also a list of items. .. note:: - The default text for the header when displaying data from a Queryset is the verbose_name of the field. For list of any other object you must set the header text using the column_names parameter. + + The default text for the header when displaying data from a Queryset is the verbose_name of the field. For a list of any other object, you must set the header text using the column_names parameter. Table CSS ********* -You can provide the css classes that the table should have as below. +You can provide the CSS classes that the table should have as shown below. .. code-block:: python @@ -63,49 +63,49 @@ You can provide the css classes that the table should have as below. context["table"] = TableSort( self.request, self.object_list, - table_css_clases="table table-light table-striped table-sm", + table_css_classes="table table-light table-striped table-sm", sort_key_name=self.ordering_key, ) return context -Fields and exclude -****************** +Fields and Exclusion +******************* -The default behavior is to show all fields of the model. If you want to show only certain field you can set this in the fields parameter as follows. +The default behavior is to show all fields of the model. If you want to show only certain fields, you can set this in the fields parameter as follows. .. code-block:: python TableSort(request, object_list, fields=["name"]) -This code will display only the field name in the table. You can also set which fields you don't want to display. +This code will display only the field "name" in the table. You can also set which fields you don't want to display. .. code-block:: python TableSort(request, object_list, exclude=["age"]) -Any field you pass in the exclude parameter will not be display, and the others that aren't, will be. +Any field you pass in the exclude parameter will not be displayed, and the others that aren't will be. .. warning:: - The current implementation looks first for the exclude field. So if you provide both fields and exclude, all the field no matter if is in the list of field you declared in the fields parameter **will not be displayed**. + The current implementation looks for the exclude field first. So if you provide both fields and exclude, all the fields, no matter if they are in the list of fields you declared in the fields parameter, **will not be displayed**. -Customizing fields headers +Customizing Fields Headers ************************** .. code-block:: python TableSort(request, object_list, fields=["age"], column_names={"age": "Age"}) -You can set a custom header for any field. For this you can use the column_names parameter. +You can set a custom header for any field. For this, you can use the column_names parameter. .. warning:: - If you set the fields and exclude parameter to None, and you provide the column_names - parameter, all the fields that are given will be displayed. -Adding extra columns + If you set the fields and exclude parameters to None and you provide the column_names parameter, all the fields that are given will be displayed. + +Adding Extra Columns ******************** -Sometimes you may want to add a custom column to the table column. You can do this using the added_columns parameter. +Sometimes you may want to add a custom column to the table. You can do this using the added_columns parameter. .. code-block:: python @@ -121,13 +121,12 @@ Sometimes you may want to add a custom column to the table column. You can do th added_columns=[(("added_column_1", "Sum"), sum)], ) -The added_columns takes a list of tuples, following this pattern ((field_identifier, field_header), callable_function). The field_identifier is a str value to identify the field, the field_header to set the text of the header and the callable_function should be a function that takes one parameter and return a string value. The callable_function will be called for each row and the object that should be displayed is passed to as a parameter to the function. +The added_columns parameter takes a list of tuples following this pattern: ((field_identifier, field_header), callable_function). The field_identifier is a string value to identify the field, the field_header is used to set the text of the header, and the callable_function should be a function that takes one parameter and returns a string value. The callable_function will be called for each row, and the object that should be displayed is passed as a parameter to the function. - -List of items +List of Items ************* -For list of items you need to set the column_names. All the field in the dictionary will be displayed. +For a list of items, you need to set the column_names. All the fields in the dictionary will be displayed. .. code-block:: python @@ -139,12 +138,13 @@ For list of items you need to set the column_names. All the field in the diction ) .. note:: - You can use the added_columns parameter to add other custom columns the same. -Primary key + You can use the added_columns parameter to add other custom columns in the same way. + +Primary Key *********** -Sometimes you may want to show the primary key of your model, the default behavior is not to display the primary key of a Queryset since most of the time it is not useful to you this to the user. +Sometimes you may want to show the primary key of your model. The default behavior is not to display the primary key of a Queryset since it is often not useful to show this to the user. .. code-block:: python @@ -154,11 +154,10 @@ Sometimes you may want to show the primary key of your model, the default behavi show_primary_key=True, ) - -Fields order +Fields Order ************ -You can set the order to display the field in the table. For this you should use the field_order parameter. +You can set the order to display the fields in the table. For this, you should usethe field_order parameter. .. code-block:: python @@ -168,10 +167,28 @@ You can set the order to display the field in the table. For this you should use field_order=["age"], ) -This will display the age as the first column in the table. +This will display the "age" as the first column in the table. .. note:: - The field will be displayed following the order you give, but if you don't include a given field this - will be displayed as the last. The field_order parameter works as a priority list. -To see the different options you can provide please see the section :ref:`table-sort-class`. + The fields will be displayed following the order you give, but if you don't include a given field, it will be displayed as the last. The field_order parameter works as a priority list. + + +Customizing the Table Template +**************************** + +You can customize the template used for generating the table by providing a different `template_name` parameter in the TableSort constructor. By default, the template used is `'django_table_sort/table.html'`. Here's an example: + +.. code-block:: python + + TableSort( + request, + object_list, + template_name="custom_template.html", + ) + +In the above example, the `'custom_template.html'` file will be used instead of the default template for generating the table. + +To create your custom template, you can copy the contents of the default template `'django_table_sort/table.html'` and modify it according to your needs. + +To see the different options you can provide, please see the section :ref:`table-sort-class`. diff --git a/pyproject.toml b/pyproject.toml index 06897d6..0cb928c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "django-table-sort" -version = "0.5.0" +version = "0.6.0" description = "Create tables with sorting links on the headers in Django templates." authors = ["TheRealVizard "] readme = "README.md" @@ -15,22 +15,23 @@ classifiers = [ "Framework :: Django :: 3.2", "Framework :: Django :: 4.0", "Framework :: Django :: 4.1", + "Framework :: Django :: 4.2", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.7", - "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", "Topic :: Software Development :: Libraries :: Python Modules", ] [tool.poetry.dependencies] -python = ">=3.7" -django = ">=3.0" +python = ">=3.9" +django = ">=3.2" [tool.poetry.group.test.dependencies]