fix: do some small fixes and update docs

docs/configuration.rst

@@ -15,6 +15,8 @@ Here is the structure of the configuration with detailed comments explaining eac
 
     HEADLESS_CMS_SETTINGS = {
         # The class used for automatic translation of content.
+        # Alternative, using ChatGPT: "headless_cms.auto_translate.openai_translate.OpenAITranslate"
+        # You can create a translation class yourself by inheriting from BaseTranslate.
         "AUTO_TRANSLATE_CLASS": "headless_cms.auto_translate.BaseTranslate",
 
         # Preprocessing hooks for DRF Spectacular.
@@ -29,7 +31,9 @@ Here is the structure of the configuration with detailed comments explaining eac
         "GLOBAL_EXCLUDED_SERIALIZED_FIELDS": [],
 
         # The OpenAI model to use for chat-based translation.
-        "OPENAI_CHAT_MODEL": "",
+        # The default model is gpt-4-turbo because we find it slightly better than gpt-4.
+        # But you can choose any model you want here.
+        "OPENAI_CHAT_MODEL": "gpt-4-turbo",
 
         # The OpenAI client to use for translation.
         "OPENAI_CLIENT": "openai.OpenAI",
@@ -38,6 +42,8 @@ Here is the structure of the configuration with detailed comments explaining eac
         "DEFAULT_CMS_PERMISSION_CLASS": "rest_framework.permissions.AllowAny",
 
         # The host URL of the CMS.
+        # Normally, this is applied for localhost.
+        # For production, if you use django-storage, you don't need to configure this.
         "CMS_HOST": "http://localhost:8000",
     }
 

docs/how-to-use.rst

@@ -335,7 +335,7 @@ Publish/Draft & Versioning Content
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Publish/Draft content
-- Versioning content: Revert to any previously saved version
+- Versioning content: Revert to any previously saved version (click on the `History` button on the detail page)
 - Recursive publish
 
 .. image:: images/how-to-use/publish.png

docs/quick-start.rst

@@ -96,6 +96,18 @@ c) Frontend - Django Astrowind Setup
 
     npm install
 
+- Sync schemas (from your backend API schema), types (inferred from your schema), and contents (fetched from your backend):
+
+.. code-block:: shell
+
+    npm run sync:all
+
+.. note::
+    Your *schemas*, *types*, and *content* will be placed in the following files/folders respectively:
+        - src/schemas/content.ts
+        - src/types/content.ts
+        - src/content/auto-*
+
 - Run the project:
 
 .. code-block:: shell
@@ -129,23 +141,36 @@ Examples:
 d) Making Changes
 -----------------
 
-**Note:** If this is your first time using `Astro` or if you are unfamiliar with it, remember to restart the FE dev server after making API updates to ensure new API calls are made, as Astro caches your API requests.
+.. note::
+    Remember to sync content with the command `npm run sync:content` every time you want to update data from the backend.
 
 - Visit http://localhost:8000/admin/astrowind_posts/awpost/1/change/ to update the first post.
 - Update the `title` field under the `English` tab to: `Hello world`.
 - Update the `title` field under the `Vietnamese` tab to: `Xin chao`.
 - Save the post.
-- Restart the FE dev server.
-- Visit the blog page again (http://localhost:4321/en/blog). You will notice that nothing has changed. This is because the post has not been published yet, so the API call uses the published version, and the title remains unchanged.
+- Sync the API by running `npm run sync:content` in the frontend terminal. You will see that nothing updates (the
+  last line you see would be `> vite-node scripts/sync.ts`).
+- Now restart the frontend server.
+- Visit the blog page again (http://localhost:4321/en/blog). You will notice that **NOTHING HAS CHANGED** (The title
+  of the first blog is still the same). This is because the post has not been published yet, so the API call uses the
+  published version, and the title remains unchanged.
 - Visit http://localhost:8000/admin/astrowind_posts/awpost/1/change/ again. You will see `Item published (outdated).`.
 - Click the `Publish` button to publish the post.
-- Restart the FE dev server.
+- Sync the API again by running `npm run sync:content` in the frontend terminal. You will now see logs like
+  `Write to file /path/to/your/project/src/content/auto-posts/en/1.json` (and so on for other languages).
+- Restart the frontend server again.
 - Visit the blog page again. This time, you will see the updated title.
 
 e) Create a New Post and Auto-Translate Using OpenAI ChatGPT
 ------------------------------------------------------------
 
-- Open your BE project and add your OpenAI key to `OPENAI_API_KEY` in the `.env` file.
+- This option is **optional**. Make sure that you are familiar with ChatGPT (very famous now); otherwise, you can skip
+  this section.
+- Open your backend project and add your OpenAI key to `OPENAI_API_KEY` in the `.env` file.
+
+.. note::
+    You can create your OpenAI keys at: https://platform.openai.com/api-keys.
+
 - Restart the BE server.
 - Visit http://localhost:8000/admin/astrowind_posts/awpost/add/
 - Fill out the post in `English`, for example:
@@ -159,15 +184,35 @@ e) Create a New Post and Auto-Translate Using OpenAI ChatGPT
 
     This is the greeting, said in English.
 
-- Updated date: Click on `today` and `now` to auto-populate.
+- Publish date: Click on `today` and `now` to auto-populate.
 - Click `Save and continue editing`.
 - Click the `Translate missing` button to use AI to translate the post into other languages.
 - Click `Publish` to publish the post.
+- Sync the API by running `npm run sync:content` in the frontend terminal.
 - Restart the FE dev server.
 - Visit http://localhost:4321/en/blog to see the new post at the top of the page.
 - Click the post to view its details.
 - Select other languages to see the post translated into different languages.
 
+Troubleshooting
+---------------
+- How to add other languages:
+
+  - On the backend side, refer to the :ref:`Translation` documentation for more information.
+  - On the frontend side, visit `src/utils/languages.ts` and uncomment (add) your desired languages. You can also
+    change your default language as well.
+
+- When I increase the number of languages, the `npm run sync:content` command raises errors, and on the backend side,
+  I see some `Broken Pipe` logs.
+
+  - This is because the Django *runserver* command cannot handle multiple concurrent requests well. You can migrate
+    to use the uvicorn command. For example:
+
+.. code-block:: shell
+
+    uvicorn config.wsgi:application --app-dir ./your_project_slug --host 0.0.0.0 --interface wsgi
+
+
 
 **And that's all about getting started with Django-headless-cms in conjunction with Astrowind. For more information,
 explore the other sections of the documentation.**

headless_cms/admin.py

@@ -196,6 +196,10 @@ def force_translate(modeladmin, request, queryset):
 RECURSIVELY_TRANSLATE = {"_recursively_translate", "_recursively_force_translate"}
 TRANSLATE_ACTIONS = {"_translate"} | FORCE_TRANSLATE | RECURSIVELY_TRANSLATE
 
+PUBLISH_ACTIONS = {"_publish", "_unpublish", "_recursively_publish"}
+
+HEADLESS_CMS_ACTIONS = PUBLISH_ACTIONS | TRANSLATE_ACTIONS
+
 
 class EnhancedLocalizedVersionAdmin(
     ImportExportActionModelAdmin, LocalizedFieldsAdminMixin, VersionAdmin
@@ -305,22 +309,26 @@ def change_view(self, request, object_id, form_url="", extra_context=None):
         obj: LocalizedPublicationModel = self.get_object(request, unquote(object_id))
 
         request_post_keys = set(request.POST.keys())
-        res = self.changeform_view(request, object_id, form_url, extra_context)
 
-        if "_unpublish" in request_post_keys:
-            obj.unpublish(request.user)
-        elif "_publish" in request_post_keys:
-            obj.publish(request.user)
-        elif "_recursively_publish" in request_post_keys:
-            obj.recursively_publish(request.user)
-        elif not TRANSLATE_ACTIONS.isdisjoint(request_post_keys):
-            force = not FORCE_TRANSLATE.isdisjoint(request_post_keys)
-            recursively = not RECURSIVELY_TRANSLATE.isdisjoint(request_post_keys)
-            if recursively:
-                obj.recursively_translate(request.user, force)
-            else:
-                obj.translate(request.user, force)
-        return res
+        if not HEADLESS_CMS_ACTIONS.isdisjoint(request_post_keys):
+            res = self.changeform_view(request, object_id, form_url, extra_context)
+
+            if "_unpublish" in request_post_keys:
+                obj.unpublish(request.user)
+            elif "_publish" in request_post_keys:
+                obj.publish(request.user)
+            elif "_recursively_publish" in request_post_keys:
+                obj.recursively_publish(request.user)
+            elif not TRANSLATE_ACTIONS.isdisjoint(request_post_keys):
+                force = not FORCE_TRANSLATE.isdisjoint(request_post_keys)
+                recursively = not RECURSIVELY_TRANSLATE.isdisjoint(request_post_keys)
+                if recursively:
+                    obj.recursively_translate(request.user, force)
+                else:
+                    obj.translate(request.user, force)
+            return res
+        else:
+            return super().change_view(request, object_id, form_url, extra_context)
 
     def response_change(self, request, obj):
         """

headless_cms/settings.py

@@ -10,7 +10,7 @@
     ],
     "AUTO_TRANSLATE_IGNORES": [],
     "GLOBAL_EXCLUDED_SERIALIZED_FIELDS": [],
-    "OPENAI_CHAT_MODEL": "",
+    "OPENAI_CHAT_MODEL": "gpt-4-turbo",
     "OPENAI_CLIENT": "openai.OpenAI",
     "DEFAULT_CMS_PERMISSION_CLASS": "rest_framework.permissions.AllowAny",
     "CMS_HOST": "http://localhost:8000",