Documents should be documented like images

[alexgleason]

There's a section on creating image fields and templating them in the Wagtail docs. It would be nice to also include a section on creating document fields. Without it, the developer needs to view the Wagtail source code to know how to implement it.

Also feel free to reame this issue to something more explicit than "please document documents"...

[m1kola]

Related question (and answer) on StackOverflow: http://stackoverflow.com/a/43389396/896843

[SalahAdDin]

👍

[lb-]

I think it would be good to have cross links to document management commands, using in templates (as called out on the main description), settings that impact the way documents are served.

Finding out about documents currently is a bit haphazard.

[lb-]

Proposed approach.

Add ~4 new sub-pages to https://docs.wagtail.org/en/stable/advanced_topics/documents/index.html (in docs/advanced_topics/documents)

1. Overview /basics page

• Covers including the app 'wagtail.documents' in INSTALLED_APPS
• Covers including URLs from wagtail.documents import urls as wagtaildocs_urls etc
• Explain that by default they will be included in the references index
• Add a Page example with a document file, then the page template that will make a link to that file available.
• How the work within collections (cross link) and can be made private using private collections
• Made available through the API via wagtail.documents.api.v2.views.DocumentsAPIViewSet - with a cross link to the relevant API section

2. Rich text

• Reference to document-link usage with simple example

3. Customising the document upload form

• WAGTAILDOCS_DOCUMENT_FORM_BASE link to setting with code example (maybe a simple T&C checkbox that the file was not created by AI :) that has to get checked on the clean method but is not saved to the Document model )
• Link to the already created sub-pages for custom Document models and customising the upload title.

4. Storing and serving

• Explain how files are stored - cross link to https://docs.wagtail.org/en/stable/advanced_topics/deploying.html#user-uploaded-files + reference to the setting DEFAULT_FILE_STORAGE
• Link to WAGTAILDOCS_SERVE_METHOD with an example
• Link to WAGTAILDOCS_CONTENT_TYPES with an example
• Link to WAGTAILDOCS_INLINE_CONTENT_TYPES with an example
• Link to WAGTAILDOCS_EXTENSIONS - with examples & link to https://docs.djangoproject.com/en/3.1/ref/validators/#fileextensionvalidator (the latest version of this)
• Cross link & document DOCUMENT_PASSWORD_REQUIRED_TEMPLATE with example

Most of this is just bringing cross-links to a central place and then adding supporting content.

I can see why we have not done this yet as the info is 'there', it's just not available in the obvious place (the section about documents).

[NXPY123]

I've added the Overview/basics page. Can you verify the changes so I know I've understood the requirements you described correctly?

[NXPY123]

Is the second page supposed to show how to insert links to documents into body text?

[lb-]

Is the second page supposed to show how to insert links to documents into body text?

I think that's covered by existing rich text rendering. I was thinking more about how to turn on/off the rich text feature.