Documentation - Add New Sections to Documents

[NXPY123]

Based on #2001.
Adds Overview page to the documents section.

Please check the following:

• For new features: Has the documentation been updated accordingly

[squash-labs]

Manage this branch in Squash

Test this branch here: https://nxpy123docs2001-document-docum-25xui.squash.io

[lb-]

Quick drive-by comment, I'd recommend we avoid any screenshot additions for now.

Screenshots add a maintenance overhead that's probably not worth it for this section of the docs.

Can you update the PR to remove these?

Thanks for preparing this, it's really appreciated.

[NXPY123]

Yepp I'll remove them

[NXPY123]

@lb- I'm not sure what's actually supposed to be in the Customising the document upload form subpage. I was able to create a custom document upload form like this:

blog/forms.py

from django import forms
from wagtail.documents.forms import BaseDocumentForm
from wagtail.documents.models import Document
class CustomDocumentForm(BaseDocumentForm):
    class Meta:
        model = Document
        fields = "__all__"

    terms_and_conditions = forms.BooleanField(
        label='I confirm that this document was not created by AI.',
        required=True
    )
    
    def clean(self):
        cleaned_data = super().clean()
        if not cleaned_data.get('terms_and_conditions'):
            raise forms.ValidationError('You must confirm the document was not created by AI.')
        return cleaned_data

template/blog/upload_document.html

<!-- myapp/upload_document.html -->

<form method="post" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Upload Document</button>
  </form>
  

blog/views.py

from django.shortcuts import render
from blog.forms import CustomDocumentForm

def upload_document(request):
    if request.method == 'POST':
        form = CustomDocumentForm(request.POST, request.FILES)
        if form.is_valid():
            form.save()
            # Handle a successful upload, e.g., redirect to a success page
    else:
        form = CustomDocumentForm()
    
    return render(request, 'blog/upload_document.html', {'form': form})

site/urls.py

from blog.views import upload_document

urlpatterns = [
    path('upload-document/', upload_document, name='upload_document'),
]

This is how it would look like:

Is this what you meant or was it something else?

[NXPY123]

Oh sorry I think I got it. Is this what you meant:

blog/forms.py

from django import forms
from wagtail.documents.forms import BaseDocumentForm
from wagtail.documents.models import Document
class CustomDocumentForm(BaseDocumentForm):
  

    terms_and_conditions = forms.BooleanField(
        label='I confirm that this document was not created by AI.',
        required=True
    )
    
    def clean(self):
        cleaned_data = super().clean()
        if not cleaned_data.get('terms_and_conditions'):
            raise forms.ValidationError('You must confirm the document was not created by AI.')
        return cleaned_data

settings/base.py

WAGTAILDOCS_DOCUMENT_FORM_BASE = 'blog.forms.CustomDocumentForm'

[lb-]

@NXPY123 I have had to do a bit of clean up but mostly this is looking great.

Points of feedback

1. Titles should be sentence case, not Title Case (e.g. Working within collections not Working Within Collections).
2. We do not need this to be as wordy, I have stripped out a bunch of the intro text that explain how Wagtail works broadly and instead tried to keep focus on the actual functionality in each part.
3. Merge rich_text_docs into overview, this did not really make sense as its own page in hindsight.
4. Keep code examples together, no need to first explain the imports and then explain how to use the imports in models. When a code snippet is less than maybe ~10 lines, one code block is enough.
5. Consistently use get_document_model, sometimes it may make sense to use the base Document (e.g. for form usage) but for the most part we should always use get_document_model, this way the developer does not have to change their code if they also use a custom document model.
6. Rich text example needed a rework - this did not really explain how to use/not use the 'document-link' feature, so I just changed this example.
7. Avoid a ref at the top of the pages that is the same name as the file, this causes some issues with MyST refs, instead just reference the document name OR use a different name.
8. Removed a few note usages, just kept the ones that were really needed, the rest can be lines under the snippets.
9. Re-ordered the contents on index, putting overview on the top etc.

This is an incredible effort thank you, I think this offers a good balance of showing how to use some features but also directing devs to the 'right' place in the docs if it already exists.

I will push up some changes, check the build runs and merge in.

[NXPY123]

Thanks for the feedback! I'll keep them in mind when I make changes from now on 🙌