#56 fixed headings hierarchy + some additional documentation

ephes · Feb 5, 2023 · a7c0fb8 · a7c0fb8
1 parent f408a6c
commit a7c0fb8
Show file tree

Hide file tree

Showing 49 changed files with 180 additions and 59 deletions.
diff --git a/docs/features.rst b/docs/features.rst
@@ -1,8 +1,10 @@
+########
 Features
-========
+########
 
+************
 Django-Admin
-------------
+************
 
 The file sizes of an audio object are cached automatically. But
 for old audio objects there's an admin action where you can update
@@ -12,11 +14,16 @@ the file size cache for all associated audio files.
   :width: 800
   :alt: Show the admin action to update the file size cache
 
+.. include:: social-media.rst
+
+.. include:: spamfilter.rst
+
+****
 Blog
-----
+****
 
 Blog / Podcast Author
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 If you set the custom `CharField` field named `author` on a Blog-Page
 using the Wagtail or Django-Admin interface, the content of this field

diff --git a/docs/howto/index.rst b/docs/howto/index.rst
@@ -0,0 +1,102 @@
+#####
+Howto
+#####
+
+This is mainly for me to remember how to do things 😁.
+
+****************
+Database Changes
+****************
+
+Migration with Restore from Backup
+==================================
+
+Sometimes it's not possible to do database changes via a Django migration.
+For example if you try to split up a model inheriting from Wagtails page
+model, it's not possible to add / remove pages via a Django Migration
+because you don't have access to the Page model in a migration
+(only the database).
+
+Atm the best option for me is to copy the production database locally,
+do the migration in a notebook and then backup the migrated database and
+restore it in production. A manual migration is only needed for a database
+where there are models which should be added to the new model.
+
+Steps
+-----
+
+#. Backup old production database
+	#. Fetch production database and restore it to the local development database
+	#. Set site to localhost in wagtailadmin
+#. Migrate the database structure
+	#. Add a new model inheriting from the old one and prefix the attributes you want to keep with `new_`
+	#. Create a new migration
+	#. Use `flit install -s` to install the `django-cast <https://github.com/ephes/django-cast>`_. package in the venv of your application
+	#. Migrate
+#. Migrate the database data manually
+	#. Use a jupyter notebook to copy the old models over to the new model [example]_
+	#. Make sure to prefix uniqe page fields like `slug` with `new` first and rename it afterwards
+	#. Remove the moved attributes from the old model
+	#. Rename the attributes prefixed with `new_` in the new model
+#. Dump local database and restore to production
+	#. Change site back to `python-podcast.staging.wersdoerfer.de` with port `443`
+	#. `pg_dump python_podcast | gzip > backups/db.staging.psql.gz`
+	#. `cd deploy && ansible-playbook restore_database.yml --limit staging`
+
+
+.. [example] blog_to_podcast example
+
+    .. code-block:: python
+
+        def blog_to_podcast(blog, content_type):
+            exclude = {"id", "page_ptr_id", "page_ptr", "translation_key"}
+            kwargs = {
+                f.name: getattr(blog, f.name)
+                for f in Blog._meta.fields
+                if f.name not in exclude
+            }
+            kwargs["slug"] = f"new_{blog.slug}"
+            kwargs["content_type"] = content_type
+            kwargs["new_itunes_artwork"] = blog.itunes_artwork
+            kwargs["new_itunes_categories"] = blog.itunes_categories
+            kwargs["new_keywords"] = blog.keywords
+            kwargs["new_explicit"] = blog.explicit
+            return Podcast(**kwargs)
+
+        # first migration to add podcast model
+        from django.core.management import call_command
+        call_command("migrate")
+
+        # get the original blog + parent
+        original_slug = "show"
+        blog = Blog.objects.get(slug=original_slug)
+        blog_parent = Page.objects.parent_of(blog).first()
+
+        # fix hostname and port
+        site = Site.objects.first()
+        site.hostname = "localhost"
+        site.port = 8000
+        site.save()
+
+        # create new page
+        podcast_content_type = ContentType.objects.get(app_label="cast", model="podcast")
+        podcast = blog_to_podcast(blog, podcast_content_type)
+        podcast = blog_parent.add_child(instance=podcast)
+
+        # fix treebeard, dunno why this is needed
+        from django.core.management import call_command
+        call_command("fixtree")
+        podcast = Podcast.objects.get(slug=f"new_{origninal_slug}")  # super important!
+
+        # move children - this is extremely brittle!
+        from wagtail.actions.move_page import MovePageAction
+        for child in blog.get_children():
+            mpa = MovePageAction(child, podcast, pos="last-child")
+            mpa.execute()
+
+        # delete old page
+        blog.delete()
+
+        # restore slug
+        podcast.slug = original_slug
+        podcast.save()
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,8 +1,9 @@
+###########
 Django Cast
-===========
+###########
 
 Welcome to the Django Cast documentation! Django Cast is blogging / podcasting
-package for Django based on `Wagtail <https://wagtail.org/>`_.
+package for `Django <https://https://www.djangoproject.com/>`_ based on `Wagtail <https://wagtail.org/>`_.
 
 This documentation is still in development and there are a lot of blanks to
 fill since Django Cast switched to Wagtail.
@@ -14,7 +15,6 @@ fill since Django Cast switched to Wagtail.
    installation
    contributing
    features
-   spamfilter
-   social-media
-   releases/index
+   howto/index
    release
+   releases/index
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,4 +1,5 @@
+************
 Installation
-============
+************
 
 This is just a dummy for now.
diff --git a/docs/release.rst b/docs/release.rst
@@ -1,5 +1,6 @@
+***************
 Release Process
-===============
+***************
 
 Bump Version Number
 -------------------

diff --git a/docs/releases/0.1/0.1.0.rst b/docs/releases/0.1/0.1.0.rst
@@ -1,4 +1,4 @@
 0.1.0 (2018-11-05)
-++++++++++++++++++
+------------------
 
 * First release on PyPI.
diff --git a/docs/releases/0.1/0.1.1.rst b/docs/releases/0.1/0.1.1.rst
@@ -1,4 +1,4 @@
 0.1.1 (2018-11-07)
-++++++++++++++++++
+------------------
 
 * Travis build is ok.
diff --git a/docs/releases/0.1/0.1.10.rst b/docs/releases/0.1/0.1.10.rst
@@ -1,5 +1,5 @@
 0.1.10 (2019-03-21)
-+++++++++++++++++++
+-------------------
 
 * Dont limit the number of items in feed (was 5 items)
 * Workaround for ogg files (ending differs for Audio model field name)

diff --git a/docs/releases/0.1/0.1.11.rst b/docs/releases/0.1/0.1.11.rst
@@ -1,4 +1,4 @@
 0.1.11 (2019-03-21)
-+++++++++++++++++++
+-------------------
 
 * Fixed requirements for package
diff --git a/docs/releases/0.1/0.1.12.rst b/docs/releases/0.1/0.1.12.rst
@@ -1,4 +1,4 @@
 0.1.12 (2019-03-22)
-+++++++++++++++++++
+-------------------
 
 * Improved installation documentation
diff --git a/docs/releases/0.1/0.1.13.rst b/docs/releases/0.1/0.1.13.rst
@@ -1,4 +1,4 @@
 0.1.13 (2019-03-22)
-+++++++++++++++++++
+-------------------
 
 * Release to update read the docs
diff --git a/docs/releases/0.1/0.1.14.rst b/docs/releases/0.1/0.1.14.rst
@@ -1,4 +1,4 @@
 0.1.14 (2019-03-23)
-+++++++++++++++++++
+-------------------
 
 * Added rtfd configuration file to be able to use python 3 :/
diff --git a/docs/releases/0.1/0.1.15.rst b/docs/releases/0.1/0.1.15.rst
@@ -1,4 +1,4 @@
 0.1.15 (2019-03-23)
-+++++++++++++++++++
+-------------------
 
 * Trying again... rtfd still failing
diff --git a/docs/releases/0.1/0.1.16.rst b/docs/releases/0.1/0.1.16.rst
@@ -1,4 +1,4 @@
 0.1.16 (2019-03-23)
-+++++++++++++++++++
+-------------------
 
 * Finally, rtfd is working again, including screencast
diff --git a/docs/releases/0.1/0.1.17.rst b/docs/releases/0.1/0.1.17.rst
@@ -1,5 +1,5 @@
 0.1.17 (2019-04-15)
-+++++++++++++++++++
+-------------------
 
 * Added chaptermarks feature
 * Duration is now displayed correctly in podlove player

diff --git a/docs/releases/0.1/0.1.18.rst b/docs/releases/0.1/0.1.18.rst
@@ -1,5 +1,5 @@
 0.1.18 (2019-04-18)
-+++++++++++++++++++
+-------------------
 
 * Fixed broken update view due to empty chaptermarks + test
 * Fixed two image/video javascript bugs
diff --git a/docs/releases/0.1/0.1.19.rst b/docs/releases/0.1/0.1.19.rst
@@ -1,5 +1,5 @@
 0.1.19 (2019-04-24)
-+++++++++++++++++++
+-------------------
 
 * Added fulltext search
 * Added filtering by date + some faceted navigation support

diff --git a/docs/releases/0.1/0.1.2.rst b/docs/releases/0.1/0.1.2.rst
@@ -1,5 +1,5 @@
 0.1.2 (2018-11-08)
-++++++++++++++++++
+------------------
 
 * Added some requirements
 * Release Documentation
diff --git a/docs/releases/0.1/0.1.20.rst b/docs/releases/0.1/0.1.20.rst
@@ -1,5 +1,5 @@
 0.1.20 (2019-04-24)
-+++++++++++++++++++
+-------------------
 
 * Fixed version history
 * Better release docs
diff --git a/docs/releases/0.1/0.1.21.rst b/docs/releases/0.1/0.1.21.rst
@@ -1,5 +1,5 @@
 0.1.21 (2019-04-24)
-+++++++++++++++++++
+-------------------
 
 * Fixed package dependencies
 * Better release docs
diff --git a/docs/releases/0.1/0.1.22.rst b/docs/releases/0.1/0.1.22.rst
@@ -1,5 +1,5 @@
 0.1.22 (2019-04-28)
-+++++++++++++++++++
+-------------------
 
 * Use proper time field for chaptermark start instead of char
 * Improved test coverage

diff --git a/docs/releases/0.1/0.1.23.rst b/docs/releases/0.1/0.1.23.rst
@@ -1,5 +1,5 @@
 0.1.23 (2019-05-16)
-+++++++++++++++++++
+-------------------
 
 * Comment en/disabling per site/blog/post
 * Fix duration extraction and small issues with the installation docs @jnns

diff --git a/docs/releases/0.1/0.1.24.rst b/docs/releases/0.1/0.1.24.rst
@@ -1,5 +1,5 @@
 0.1.24 (2019-05-22)
-+++++++++++++++++++
+-------------------
 
 * Use blog.email as itunes:email instead of blog.user.email
 * Added author field to have user editable author name

diff --git a/docs/releases/0.1/0.1.25.rst b/docs/releases/0.1/0.1.25.rst
@@ -1,5 +1,5 @@
 0.1.25 (2019-05-23)
-+++++++++++++++++++
+-------------------
 
 * Bugfix: i18n should now work, finally
 * Bugfix: Allow empty chaptermarks text field + test
diff --git a/docs/releases/0.1/0.1.26.rst b/docs/releases/0.1/0.1.26.rst
@@ -1,4 +1,4 @@
 0.1.26 (2019-05-23)
-+++++++++++++++++++
+-------------------
 
 * Bugfix: i18n should now work, finally!!1 duh
diff --git a/docs/releases/0.1/0.1.27.rst b/docs/releases/0.1/0.1.27.rst
@@ -1,5 +1,5 @@
 0.1.27 (2019-05-27)
-+++++++++++++++++++
+-------------------
 
 * Extended documentation
 * It's now possible to mark content as "for post detail page" only

diff --git a/docs/releases/0.1/0.1.28.rst b/docs/releases/0.1/0.1.28.rst
@@ -1,5 +1,5 @@
 0.1.28 (2019-06-03)
-+++++++++++++++++++
+-------------------
 
 * Added some analytics support: import your access.log and view dashboard with hits/day,week
 * Fixed pub_date bug, leading to safari not being able to update posts + some tests

diff --git a/docs/releases/0.1/0.1.29.rst b/docs/releases/0.1/0.1.29.rst
@@ -1,3 +1,4 @@
 0.1.29 (2020-01-03)
-+++++++++++++++++++
+-------------------
+
 * Use poetry instead of requirements.txt and setup.py
diff --git a/docs/releases/0.1/0.1.3.rst b/docs/releases/0.1/0.1.3.rst
@@ -1,5 +1,5 @@
 0.1.3 (2018-11-17)
-++++++++++++++++++
+------------------
 
 * Fixed css/static icons
 * Merged pull request from SmartC2016 to fix javascript block issue

diff --git a/docs/releases/0.1/0.1.30.rst b/docs/releases/0.1/0.1.30.rst
@@ -1,4 +1,5 @@
 0.1.30 (2020-10-25)
-+++++++++++++++++++
+-------------------
+
 * fixed some logfile parsing bug
 * tried to add wagtail but removed it again
diff --git a/docs/releases/0.1/0.1.31.rst b/docs/releases/0.1/0.1.31.rst
@@ -1,3 +1,4 @@
 0.1.31 (never released)
-+++++++++++++++++++++++
+-----------------------
+
 * Trying to use vuepress for documentation
diff --git a/docs/releases/0.1/0.1.32.rst b/docs/releases/0.1/0.1.32.rst
@@ -1,3 +1,4 @@
 0.1.32 (never released)
-+++++++++++++++++++++++
+-----------------------
+
 * not clear
diff --git a/docs/releases/0.1/0.1.33.rst b/docs/releases/0.1/0.1.33.rst
@@ -1,3 +1,4 @@
 0.1.33 (never released)
-+++++++++++++++++++++++
+-----------------------
+
 * dont know anymore
diff --git a/docs/releases/0.1/0.1.34.rst b/docs/releases/0.1/0.1.34.rst
@@ -1,3 +1,4 @@
 0.1.34 (never released)
-+++++++++++++++++++++++
+-----------------------
+
 * dont know anymore
diff --git a/docs/releases/0.1/0.1.35.rst b/docs/releases/0.1/0.1.35.rst
@@ -1,3 +1,4 @@
 0.1.35 (2020-10-25)
-+++++++++++++++++++++++
+-------------------
+
 * last package released that is based on `master` branch
diff --git a/docs/releases/0.1/0.1.4.rst b/docs/releases/0.1/0.1.4.rst
@@ -1,5 +1,5 @@
 0.1.4 (2018-11-18)
-++++++++++++++++++
+------------------
 
 * Include css via cast_base.html
 * audio fixes
diff --git a/docs/releases/0.1/0.1.5.rst b/docs/releases/0.1/0.1.5.rst
@@ -1,5 +1,5 @@
 0.1.5 (2018-11-21)
-++++++++++++++++++
+------------------
 
 * basic feed support (rss/atom) for podcasts
 * travis now runs tests with ffprobe, too

diff --git a/docs/releases/0.1/0.1.6.rst b/docs/releases/0.1/0.1.6.rst
@@ -1,5 +1,5 @@
 0.1.6 (2019-02-28)
-++++++++++++++++++
+------------------
 
 * Use filepond for media uploads (images video)
 * Improved portrait video support

diff --git a/docs/releases/0.1/0.1.7.rst b/docs/releases/0.1/0.1.7.rst
@@ -1,4 +1,4 @@
 0.1.7 (2019-02-28)
-++++++++++++++++++
+------------------
 
 * forgot linting