Chore: Unify and Update Docs (#1148)

* docs fix

* Unify documentation structure and setup GitHub Pages deployment

- Consolidate documentation from tickets, talk, and video into /doc
- Move talk docs from talk/doc to doc/talk
- Move video docs from video/docs to doc/video
- Configure automated deployment to docs.eventyay.com via GitHub Actions
- Update Sphinx configurations with Eventyay branding
- Switch to alabaster theme with custom CSS
- Add comprehensive README.md with build instructions
- Configure CNAME for custom domain
- Remove legacy documentation folders

* acheive comprehensive documentation

* fix deployment and workflows

* remove duplication

* acheived higher coverage for components fixed typos

---------

Co-authored-by: Mario Behling <[email protected]>

Author: Saksham-Sirohi

.github/workflows/deploy-docs.yml

@@ -0,0 +1,103 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - enext
+      - main
+    paths:
+      - 'doc/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            enchant-2 \
+            libffi-dev \
+            libssl-dev \
+            libxml2-dev \
+            libxslt1-dev \
+            gettext \
+            libfreetype-dev \
+            libjpeg-dev \
+            libpq-dev \
+            build-essential
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          cd doc
+          # Install all dependencies (Sphinx, Django, and all packages)
+          bash install-all-deps.sh
+
+      - name: Build unified documentation
+        run: |
+          cd doc
+          # Set environment variables (conf.py handles Django setup automatically)
+          export DJANGO_SETTINGS_MODULE=eventyay.config.settings
+          export EVENTYAY_CONFIG_FILE=$(pwd)/eventyay-docs.cfg
+          export DATABASE_URL="sqlite:///:memory:"
+          export REDIS_URL="redis://localhost:6379/0"
+          export MPLCONFIGDIR=/tmp/matplotlib
+          mkdir -p $MPLCONFIGDIR
+          # Build documentation
+          make html
+
+      - name: Prepare deployment
+        run: |
+          mkdir -p _site
+          # Copy unified documentation (includes all components: tickets, talk, video)
+          echo "Copying unified documentation..."
+          cp -r doc/_build/html/* _site/
+          # Copy CNAME for custom domain (docs.eventyay.com)
+          cp doc/CNAME _site/
+          # Create .nojekyll to prevent GitHub Pages from ignoring files starting with _
+          touch _site/.nojekyll
+          # List contents for verification
+          echo "Documentation site structure:"
+          ls -la _site/
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.github/workflows/gh-pages-deploy.yml

@@ -19,6 +19,10 @@ __pycache__/
 .mypy_cache/
 .ipython/
 _static/
+# Exception: Track documentation static files
+!doc/_static/
+!doc/talk/_static/
+!doc/video/_static/
 .idea
 .secret
 atlassian-ide-plugin.xml

.gitignore

@@ -74,6 +74,7 @@ class Meta:
         }
 
     class urls(EventUrls):
+        """URL patterns for SubmitterAccessCode model views."""
         base = edit = '{self.event.cfp.urls.access_codes}{self.code}/'
         send = '{base}send'
         delete = '{base}delete/'

app/eventyay/base/models/access_code.py

@@ -738,6 +738,7 @@ def reset_password(self, event, user=None, mail_text=None, orga=False):
     reset_password.alters_data = True
 
     class orga_urls(EventUrls):
+        """URL patterns for organizer panel views related to this user."""
         admin = '/orga/admin/users/{self.code}/'
 
     @transaction.atomic

app/eventyay/base/models/auth.py

@@ -65,8 +65,21 @@ def is_field_required(self, field):
         return self.fields.get(field, default_fields()[field])['visibility'] == 'required'
 
     for field in default_fields().keys():
-        setattr(cls, f'request_{field}', property(partial(is_field_requested, field=field)))
-        setattr(cls, f'require_{field}', property(partial(is_field_required, field=field)))
+        # Create wrapper functions with clean docstrings to avoid RST formatting issues
+        def make_request_getter(field_name):
+            def getter(self):
+                return is_field_requested(self, field_name)
+            getter.__doc__ = f"Check if {field_name} field is requested."
+            return getter
+        
+        def make_require_getter(field_name):
+            def getter(self):
+                return is_field_required(self, field_name)
+            getter.__doc__ = f"Check if {field_name} field is required."
+            return getter
+        
+        setattr(cls, f'request_{field}', property(make_request_getter(field)))
+        setattr(cls, f'require_{field}', property(make_require_getter(field)))
     return cls
 
 
@@ -103,6 +116,7 @@ class CfP(PretalxModel):
     fields = models.JSONField(default=default_fields)
 
     class urls(EventUrls):
+        """URL patterns for public CfP (Call for Proposals) views."""
         base = '{self.event.orga_urls.cfp}'
         editor = '{base}flow/'
         questions = '{base}questions/'

app/eventyay/base/models/cfp.py

@@ -564,7 +564,7 @@ class Event(
     tickets for.
 
     :param organizer: The organizer this event belongs to
-    :type organizer: Organizer
+    :type organizer: eventyay.base.models.organizer.Organizer
     :param testmode: This event is in test mode
     :type testmode: bool
     :param name: This event's full title
@@ -807,6 +807,7 @@ class Event(
     )
 
     class urls(EventUrls):
+        """URL patterns for public/frontend views of this event."""
         base_path = settings.BASE_PATH
         base = '{base_path}/{self.slug}/'
         login = '{base}login/'
@@ -837,6 +838,7 @@ class urls(EventUrls):
         settings_css = '{base}static/event.css'
 
     class orga_urls(EventUrls):
+        """URL patterns for organizer/admin panel views of this event."""
         base_path = settings.BASE_PATH
         base = '{base_path}/orga/event/{self.slug}/'
         login = '{base}login/'
@@ -890,6 +892,7 @@ class orga_urls(EventUrls):
         new_information = '{base}info/new/'
 
     class api_urls(EventUrls):
+        """URL patterns for API endpoints related to this event."""
         base_path = settings.TALK_BASE_PATH
         base = '{base_path}/api/events/{self.slug}/'
         submissions = '{base}submissions/'
@@ -910,6 +913,7 @@ class api_urls(EventUrls):
         speaker_information = '{base}speaker-information/'
 
     class tickets_urls(EventUrls):
+        """URL patterns for ticket/control panel views of this event."""
         _full_base_path = settings.BASE_PATH
         base_path = urlparse(_full_base_path).path.rstrip('/')
         base = '{base_path}/control/'

app/eventyay/base/models/event.py

@@ -59,6 +59,7 @@ def log_parent(self):
         return self.event
 
     class orga_urls(EventUrls):
+        """URL patterns for organizer panel views of speaker information."""
         base = edit = '{self.event.orga_urls.information}{self.pk}/'
         delete = '{base}delete/'
 

app/eventyay/base/models/information.py

@@ -115,6 +115,7 @@ class Meta:
         }
 
     class urls(EventUrls):
+        """URL patterns for mail template views."""
         base = edit = '{self.event.orga_urls.mail_templates}{self.pk}/'
         delete = '{base}delete/'
 
@@ -344,6 +345,7 @@ class Meta:
         }
 
     class urls(EventUrls):
+        """URL patterns for queued mail views."""
         base = edit = '{self.event.orga_urls.mail}{self.pk}/'
         delete = '{base}delete'
         send = '{base}send'

app/eventyay/base/models/mail.py

@@ -211,7 +211,8 @@ class PretalxModel(
     metaclass=RulesModelBase,
 ):
     """
-    Base model for most pretalx models. Suitable for plugins.
+    Base model for most Eventyay models. Suitable for plugins.
+    Provides scoped object management, logging, timestamps, and file cleanup.
     """
 
     objects = ScopedManager(event='event')