chore: update docs (#282)

* chore: update docs * chore: feeds doc update * chore: immporters and sites * update docs
APSL · Jun 26, 2024 · cf15c02 · cf15c02
1 parent 7b21080
commit cf15c02
Show file tree

Hide file tree

Showing 11 changed files with 77 additions and 28 deletions.
diff --git 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
@@ -1 +1,2 @@
-.. include:: ../CHANGELOG
+
+.. include:: ../CHANGELOG.md
diff --git 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
@@ -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 <http://docs.wagtail.io/en/v2.0/editor_manual/index.html>`_ for further details
+Please visit `Wagtail: an Editor’s guide <https://guide.wagtail.org/en-latest/>`_ 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
@@ -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
diff --git 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
@@ -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
diff --git a/docs/settings.rst b/docs/settings.rst
@@ -3,32 +3,26 @@ 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
 ---------------
 **Default value:** ``False`` (Empty string)
 
 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
@@ -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 <http://docs.wagtail.io/en/v1.1/advanced_topics/settings.html#ready-to-use-example-configuration-files>`_.
+7. Configure the :code:`MEDIA_ROOT` and :code:`MEDIA_URL` settings as described in the `Wagtail Docs <https://docs.wagtail.org/en/latest/getting_started/integrating_into_django.html>`_.
 
 .. 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
@@ -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 <https://docs.wagtail.org/en/latest/advanced_topics/multi_site_multi_instance_multi_tenancy.html#id1>`_
 
 Single blog site
 ----------------

diff --git a/readthedocs.yaml 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