From cf15c026ec03ad36a26eefd1d2c476dc63bad404 Mon Sep 17 00:00:00 2001 From: Carlos Salom Oliver Date: Wed, 26 Jun 2024 15:34:15 +0200 Subject: [PATCH] chore: update docs (#282) * chore: update docs * chore: feeds doc update * chore: immporters and sites * update docs --- CHANGELOG.md | 9 +++++++-- docs/changelog.rst | 3 ++- docs/conf.py | 8 ++++---- docs/editors.rst | 10 ++++------ docs/feeds.rst | 1 + docs/importers.rst | 2 ++ docs/requirements.txt | 13 +++++++++++++ docs/settings.rst | 8 +------- docs/setup.rst | 24 ++++++++++++++++-------- docs/sites.rst | 1 + readthedocs.yaml | 26 ++++++++++++++++++++++++++ 11 files changed, 77 insertions(+), 28 deletions(-) create mode 100644 docs/requirements.txt create mode 100644 readthedocs.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c0b780..f71e862 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,11 +3,16 @@ Changelog Unreleased ---------- + + +2.1.1 (2024-06-25) +------------------ +* Update docs 2.1.0 (2024-06-14) ------------------ * Add Wagtail 6.1 support. Drop Wagtail <=5.2 support. - +* Add Django 5.0 support. 2.0.0 (2023-07-04) ------------------ @@ -114,7 +119,7 @@ Unreleased * Add German and Polish translations. 0.9.1 (2017-09-12) ----------------- +------------------ * Add missing migration. 0.9 (2017-08-03) diff --git a/docs/changelog.rst b/docs/changelog.rst index 0e25f5b..0b7744a 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1 +1,2 @@ -.. include:: ../CHANGELOG \ No newline at end of file + +.. include:: ../CHANGELOG.md diff --git a/docs/conf.py b/docs/conf.py index 98b4f89..2d50ff4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,16 +55,16 @@ # built documents. # # The short X.Y version. -version = '1.0' +version = '2.0' # The full version, including alpha/beta/rc tags. -release = '1.0' +release = '2.1.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -137,7 +137,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/editors.rst b/docs/editors.rst index 1c97959..95735c8 100644 --- a/docs/editors.rst +++ b/docs/editors.rst @@ -4,13 +4,11 @@ Editor's dashboard Puput uses the default Wagtail CMS admin page in order to manage the content of the blog. It provides a powerful, clean and modern interface. Just open your browser at http://127.0.0.1:8000/blog_admin/. +.. image:: https://i.imgur.com/8sp8C8Z.png + This is how adding entry page looks: -.. image:: https://i.imgur.com/QlsVfwT.png +.. image:: https://i.imgur.com/r7Mks7w.png -Please visit `Wagtail: an Editor’s guide `_ for further details +Please visit `Wagtail: an Editor’s guide `_ for further details of how to use Wagtail editor's dashboard. - -.. note:: - - If you want to edit the owner of an entry you need to install Wagtail >= 1.11. diff --git a/docs/feeds.rst b/docs/feeds.rst index 07f1dca..5a5e023 100644 --- a/docs/feeds.rst +++ b/docs/feeds.rst @@ -9,3 +9,4 @@ Feed description Set *Use short description in feeds* to False if you want to use the full blog post content as description for the feed items. When set to True (by default), Puput will try to use the blog post's excerpt or truncate the body to 70 words when the excerpt is not available. +.. image:: https://i.imgur.com/2FaYn1p_d.webp?maxwidth=760 \ No newline at end of file diff --git a/docs/importers.rst b/docs/importers.rst index ea3f3f0..ef2b5df 100644 --- a/docs/importers.rst +++ b/docs/importers.rst @@ -3,6 +3,8 @@ Import your blog data If you need to migrate a blog system to Puput we provide you a various tools to import your data. +This packages have been not review for a long time, they're on the roadmap but take it into account. + Prerequisites ------------- diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..05465ce --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,13 @@ +sphinx==7.0.1 +sphinxcontrib-applehelp==1.0.4 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.1 +sphinxcontrib-jsmath==-1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.5 +Jinja2==3.1.2 +MarkupSafe==2.1.3 +alabaster==0.7.13 +babel==2.12.1 +imagesize==1.4.1 +snowballstemmer==2.2.0 \ No newline at end of file diff --git a/docs/settings.rst b/docs/settings.rst index 293163a..9e88209 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -3,23 +3,19 @@ Settings Puput provides setting variables in order to customize your installation. -.. setting:: PUPUT_ENTRY_MODEL - PUPUT_ENTRY_MODEL ----------------- **Default value:** ``'puput.abstracts.EntryAbstract'`` (Empty string) String setting to define the base model path for Entry model. See :doc:`extending_entry` for more details. -.. setting:: PUPUT_BLOG_MODEL PUPUT_BLOG_MODEL ------------------ +---------------- **Default value:** ``'puput.abstracts.BlogAbstract'`` (Empty string) String setting to define the base model path for Blog model. See :doc:`extending_blog` for more details. -.. setting:: PUPUT_AS_PLUGIN PUPUT_AS_PLUGIN --------------- @@ -27,8 +23,6 @@ PUPUT_AS_PLUGIN Boolean setting to define if you set Puput as a plugin of a previously configured Wagtail project. -.. setting:: PUPUT_USERNAME_FIELD - PUPUT_USERNAME_FIELD -------------------- **Default value:** ``'username'`` (Empty string) diff --git a/docs/setup.rst b/docs/setup.rst index 32c8871..607a16f 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -49,19 +49,26 @@ If you are already referencing one of these apps in your :code:`INSTALLED_APPS` .. code-block:: python - MIDDLEWARE_CLASSES = ( + MIDDLEWARE = [ ... 'wagtail.contrib.redirects.middleware.RedirectMiddleware', - ) + ] 4. Add the :code:`request` context processor to the :code:`TEMPLATE_CONTEXT_PROCESSORS` structure in your Django settings. .. code-block:: python - TEMPLATE_CONTEXT_PROCESSORS = ( - ... - 'django.template.context_processors.request', - ) + TEMPLATES = [ + { + ... + "OPTIONS": { + "context_processors": [ + ... + "django.template.context_processors.request" + ] + } + } + ] 5. Set the :code:`WAGTAIL_SITE_NAME` variable to the name of your site in your Django settings. @@ -75,7 +82,7 @@ If you are already referencing one of these apps in your :code:`INSTALLED_APPS` WAGTAILADMIN_BASE_URL = 'http://localhost:8000/' -7. Configure the :code:`MEDIA_ROOT` and :code:`MEDIA_URL` settings as described in the `Wagtail Docs `_. +7. Configure the :code:`MEDIA_ROOT` and :code:`MEDIA_URL` settings as described in the `Wagtail Docs `_. .. code-block:: python @@ -107,6 +114,7 @@ If you are already referencing one of these apps in your :code:`INSTALLED_APPS` from django.views.generic.base import RedirectView urlpatterns += staticfiles_urlpatterns() # tell gunicorn where static files are in dev mode + urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) urlpatterns += static(settings.MEDIA_URL + 'images/', document_root=os.path.join(settings.MEDIA_ROOT, 'images')) urlpatterns += [ path(r'favicon\.ico', RedirectView.as_view(url=settings.STATIC_URL + 'myapp/images/favicon.ico')), @@ -120,7 +128,7 @@ If you are already referencing one of these apps in your :code:`INSTALLED_APPS` Installation on top of Wagtail ------------------------------ -0. This assumes that you have Wagtail >= 2.0 installed and you can access /admin; if this is not the case or you would like to use a newer version of Wagtail than is in the dependencies of puput, follow the steps below in a python venv: +0. This assumes that you have Wagtail >= 5.2 installed and you can access /admin; if this is not the case or you would like to use a newer version of Wagtail than is in the dependencies of puput, follow the steps below in a python venv: .. code-block:: bash diff --git a/docs/sites.rst b/docs/sites.rst index 997d12b..7e620bb 100644 --- a/docs/sites.rst +++ b/docs/sites.rst @@ -11,6 +11,7 @@ as parents and Entry pages as children. Furthermore all Blog pages must have Roo This has a powerful advantage so you can create separated sites with multiple blog instances. For instance, you could create a simple blog `http://www.example.com/blog/` and another one with videos (a videoblog) `http://www.example.com/tv/`. +More information can be found at `Wagtail Docs `_ Single blog site ---------------- diff --git a/readthedocs.yaml b/readthedocs.yaml new file mode 100644 index 0000000..6046e9c --- /dev/null +++ b/readthedocs.yaml @@ -0,0 +1,26 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +formats: + - pdf + - epub + +# We recommend specifying your dependencies to enable reproducible builds: +# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file