# Giant News
A re-usable package which can be used in any project that requires a generic `News` app.
This will include the basic formatting and functionality such as model creation via the admin.
Supported Django versions:
- Django 2.2, 3.2
Supported django CMS versions:
- django CMS 3.8, 3.9
> ⚠️ For Django 2.x, use giant-news 0.x
> ⚠️ Release 1.0.0-alpha.1 and above are NOT compatible with
> versions < 1 due to model name changes and a migration reset. Only upgrade to
> this version if you are aware of what changes need to be made
## Installation and Configuration
To install with the package manager, run:
$ poetry add giant-news
You should then add `"giant_news", "easy_thumbnails" and "filer"` to the `INSTALLED_APPS` in your settings file.
The detail pages in this app use plugins which are not contained within this app. It is recommended that you include a set of plugins in your project, or use the `giant-plugins` app.
It is highly recommended that you override the base Article model at the start
of a project, even if you have no intention of immediately changing any fields.
Changing from a non-swappable model to a swappable model is difficult and will require migration
hacking.
```
# models.py
from giant_news.models import AbstractArticle
class Article(AbstractArticle):
pass
# in admin.py
from django.contrib import admin
from giant_news.admin import ArticleAdmin
from .models import Article
admin.site.register(Article, ArticleAdmin)
```
When the migrations are created for this new model it will need some tweaking as
Django will not set this up to use swapper. To do this add the following lines to
the initial migration file (this will replace the hardcoded dependency on the
0002 migration from giant_news)
```
import swapper
class Migration...
dependencies = [
...
('giant_news', '0001_initial'),
swapper.dependency("giant_news", "Article"),
]
```
We also need to tell it run this migration before any other migration inside the
giant_news library as the model needs to be "swapped" before any relations are
created. You can do this with another line just under the `dependencies` list.
```
run_before = [
('giant_news', '0002_relatedarticlecardplugin_relatedarticleplugin'),
]
```
Once you have created a model, and only AFTER you run migrations, you'll need to
point swapper to this new model. You can do this with the following setting:
GIANT_NEWS_ARTICLE_MODEL = "appname.Article"
## Admin
By default, the admin for each of the models is not installed. This is so that you can register them as you need within your custom app. To do so add the following lines to your admin.py
```
from giant_news.admin import ArticleAdmin, TagAdmin, CategoryAdmin, AuthorAdmin
from giant_news.models import Article, Tag, Category, Author
admin.site.register(Article, ArticleAdmin)
admin.site.register(Category, CategoryAdmin)
admin.site.register(Author, AuthorAdmin)
admin.site.register(Tag, TagAdmin)
```
## CMS App
By default this app is not registered as a CMS App. However if you wish to use the builtin CMS app simply add the following line of code to the settings file.
REGISTER_NEWS_APP = True
## Sitemap
In order to add published articles to your sitemap, import the sitemaps file and add it to your `sitemaps` dict. This is usually contained within the main `urls.py` file.
## URLs
It is recommended that the application be added to a CMS page via the apphook. However, if you wish to hardcode the URL, you can do so by adding the following to your main `urls.py` file:
```
path("news/", include("giant_news.urls"), name="news"),
```
If you want to customize the urls to include a different path and/or templates, first you must import `from giant_news import views as news_views` in `core.urls` and then you could add the following:
path("news/", news_views.ArticleIndex.as_view(template_name="news/index.html"), name="index"),
path("news/<slug:slug>/", news_views.ArticleDetail.as_view(template_name="news/detail.html"), name="detail"),
# Local development
## Getting setup
To get started with local development of this library, you will need access to poetry (or another venv manager). You can set up a virtual environment with poetry by running:
$ poetry shell
Note: You can update which version of python poetry will use for the virtualenv by using:
$ poetry env use 3.x
and install all the required dependencies (seen in the pyproject.toml file) with:
$ poetry install
## Management commands
As the library does not come with a `manage.py` file we need to use `django-admin` instead. However, we will need to set our `DJANGO_SETTINGS_MODULE` file in the environment. You can do this with:
$ export DJANGO_SETTINGS_MODULE=settings
From here you can run all the standard Django management commands such as `django-admin makemigrations`.
## Testing
This library uses Pytest in order to run its tests. You can do this (inside the shell) by running:
$ pytest -v
where `-v` is to run in verbose mode which, while not necessary, will show which tests errored/failed/passed a bit more clearly.
## Preparing for release
In order to prep the package for a new release on TestPyPi and PyPi there is one key thing that you need to do. You need to update the version number in the `pyproject.toml`.
This is so that the package can be published without running into version number conflicts. The version numbering must also follow the Semantic Version rules which can be found here https://semver.org/.
## Publishing
Publishing a package with poetry is incredibly easy. Once you have checked that the version number has been updated (not the same as a previous version) then you only need to run two commands.
$ `poetry build`
will package the project up for you into a way that can be published.
$ `poetry publish`
will publish the package to PyPi. You will need to enter the company username (Giant-Digital) and password for the account which can be found in the company password manager
Raw data
{
"_id": null,
"home_page": "https://github.com/giantmade/giant-news",
"name": "giant-news",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "giant_news,app",
"author": "Will-Hoey",
"author_email": "will.hoey@giantdigital.co.uk",
"download_url": "https://files.pythonhosted.org/packages/16/b8/50b8dc651565157ec2e82e5768cca2bd018fbffe3f6d9e7816cb87d44eba/giant_news-1.2.6.tar.gz",
"platform": null,
"description": "# Giant News\n\nA re-usable package which can be used in any project that requires a generic `News` app.\n\nThis will include the basic formatting and functionality such as model creation via the admin.\n\nSupported Django versions:\n\n- Django 2.2, 3.2\n\nSupported django CMS versions:\n\n- django CMS 3.8, 3.9\n\n> ⚠️ For Django 2.x, use giant-news 0.x\n\n> ⚠️ Release 1.0.0-alpha.1 and above are NOT compatible with\n> versions < 1 due to model name changes and a migration reset. Only upgrade to\n> this version if you are aware of what changes need to be made\n\n## Installation and Configuration\n\nTo install with the package manager, run:\n\n $ poetry add giant-news\n\nYou should then add `\"giant_news\", \"easy_thumbnails\" and \"filer\"` to the `INSTALLED_APPS` in your settings file.\nThe detail pages in this app use plugins which are not contained within this app. It is recommended that you include a set of plugins in your project, or use the `giant-plugins` app.\n\nIt is highly recommended that you override the base Article model at the start\nof a project, even if you have no intention of immediately changing any fields.\nChanging from a non-swappable model to a swappable model is difficult and will require migration\nhacking.\n\n```\n# models.py\n\nfrom giant_news.models import AbstractArticle\n\n\nclass Article(AbstractArticle):\n pass\n\n\n# in admin.py\n\nfrom django.contrib import admin\nfrom giant_news.admin import ArticleAdmin\nfrom .models import Article\n\n\nadmin.site.register(Article, ArticleAdmin)\n\n```\n\nWhen the migrations are created for this new model it will need some tweaking as\nDjango will not set this up to use swapper. To do this add the following lines to\nthe initial migration file (this will replace the hardcoded dependency on the\n0002 migration from giant_news)\n\n```\nimport swapper\n\nclass Migration...\n\n dependencies = [\n ...\n ('giant_news', '0001_initial'),\n swapper.dependency(\"giant_news\", \"Article\"),\n ]\n```\nWe also need to tell it run this migration before any other migration inside the\ngiant_news library as the model needs to be \"swapped\" before any relations are\ncreated. You can do this with another line just under the `dependencies` list.\n\n```\n run_before = [\n ('giant_news', '0002_relatedarticlecardplugin_relatedarticleplugin'),\n ]\n```\nOnce you have created a model, and only AFTER you run migrations, you'll need to\npoint swapper to this new model. You can do this with the following setting:\n\n GIANT_NEWS_ARTICLE_MODEL = \"appname.Article\"\n\n\n## Admin\nBy default, the admin for each of the models is not installed. This is so that you can register them as you need within your custom app. To do so add the following lines to your admin.py\n\n```\nfrom giant_news.admin import ArticleAdmin, TagAdmin, CategoryAdmin, AuthorAdmin\nfrom giant_news.models import Article, Tag, Category, Author\n\nadmin.site.register(Article, ArticleAdmin)\nadmin.site.register(Category, CategoryAdmin)\nadmin.site.register(Author, AuthorAdmin)\nadmin.site.register(Tag, TagAdmin)\n```\n\n## CMS App\nBy default this app is not registered as a CMS App. However if you wish to use the builtin CMS app simply add the following line of code to the settings file.\n\n REGISTER_NEWS_APP = True\n\n## Sitemap\n\nIn order to add published articles to your sitemap, import the sitemaps file and add it to your `sitemaps` dict. This is usually contained within the main `urls.py` file.\n\n## URLs\n\nIt is recommended that the application be added to a CMS page via the apphook. However, if you wish to hardcode the URL, you can do so by adding the following to your main `urls.py` file:\n\n```\n\n path(\"news/\", include(\"giant_news.urls\"), name=\"news\"),\n```\n\nIf you want to customize the urls to include a different path and/or templates, first you must import `from giant_news import views as news_views` in `core.urls` and then you could add the following:\n\n path(\"news/\", news_views.ArticleIndex.as_view(template_name=\"news/index.html\"), name=\"index\"),\n path(\"news/<slug:slug>/\", news_views.ArticleDetail.as_view(template_name=\"news/detail.html\"), name=\"detail\"),\n\n# Local development\n\n## Getting setup\n\nTo get started with local development of this library, you will need access to poetry (or another venv manager). You can set up a virtual environment with poetry by running:\n\n $ poetry shell\n\nNote: You can update which version of python poetry will use for the virtualenv by using:\n\n $ poetry env use 3.x\n\nand install all the required dependencies (seen in the pyproject.toml file) with:\n\n $ poetry install\n\n\n## Management commands\n\nAs the library does not come with a `manage.py` file we need to use `django-admin` instead. However, we will need to set our `DJANGO_SETTINGS_MODULE` file in the environment. You can do this with: \n\n $ export DJANGO_SETTINGS_MODULE=settings\n\nFrom here you can run all the standard Django management commands such as `django-admin makemigrations`.\n\n## Testing\n\nThis library uses Pytest in order to run its tests. You can do this (inside the shell) by running:\n\n $ pytest -v\n\nwhere `-v` is to run in verbose mode which, while not necessary, will show which tests errored/failed/passed a bit more clearly. \n\n## Preparing for release\n\nIn order to prep the package for a new release on TestPyPi and PyPi there is one key thing that you need to do. You need to update the version number in the `pyproject.toml`.\nThis is so that the package can be published without running into version number conflicts. The version numbering must also follow the Semantic Version rules which can be found here https://semver.org/.\n\n## Publishing\n\nPublishing a package with poetry is incredibly easy. Once you have checked that the version number has been updated (not the same as a previous version) then you only need to run two commands.\n\n $ `poetry build`\n\nwill package the project up for you into a way that can be published.\n\n $ `poetry publish`\n\nwill publish the package to PyPi. You will need to enter the company username (Giant-Digital) and password for the account which can be found in the company password manager\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A small reusable package that adds a News app to a project",
"version": "1.2.6",
"project_urls": {
"Homepage": "https://github.com/giantmade/giant-news",
"Repository": "https://github.com/giantmade/giant-news"
},
"split_keywords": [
"giant_news",
"app"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d90d42e23848dbd71a83cb97127b5bed89ba0240570d2e5e1d47e824f6de207",
"md5": "7591b3c99f008f3540799150fe17d84b",
"sha256": "0a8e12da3071e3cfa072bdc9c1256f8f5ae39ca4eca3c7bf0cf7efe29948985c"
},
"downloads": -1,
"filename": "giant_news-1.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7591b3c99f008f3540799150fe17d84b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 23591,
"upload_time": "2023-07-27T14:45:05",
"upload_time_iso_8601": "2023-07-27T14:45:05.621520Z",
"url": "https://files.pythonhosted.org/packages/1d/90/d42e23848dbd71a83cb97127b5bed89ba0240570d2e5e1d47e824f6de207/giant_news-1.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16b850b8dc651565157ec2e82e5768cca2bd018fbffe3f6d9e7816cb87d44eba",
"md5": "c8e711c2a0b6d3987bcb16bc102e6458",
"sha256": "03b44e22ee181bb8d4aa397e20354884d4f126e750eb1dcf2ebc2bfbb3c91322"
},
"downloads": -1,
"filename": "giant_news-1.2.6.tar.gz",
"has_sig": false,
"md5_digest": "c8e711c2a0b6d3987bcb16bc102e6458",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 15965,
"upload_time": "2023-07-27T14:45:07",
"upload_time_iso_8601": "2023-07-27T14:45:07.138562Z",
"url": "https://files.pythonhosted.org/packages/16/b8/50b8dc651565157ec2e82e5768cca2bd018fbffe3f6d9e7816cb87d44eba/giant_news-1.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-27 14:45:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "giantmade",
"github_project": "giant-news",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "giant-news"
}
JSON
