Documentation fixes for document search and project creation

documentcloud/documents/models/document.py

@@ -33,8 +33,6 @@
 
 logger = logging.getLogger(__name__)
 
-# pylint:disable = too-many-lines
-
 
 class Document(models.Model):
     """A document uploaded to DocumentCloud"""

documentcloud/documents/views.py

@@ -573,6 +573,15 @@ def bulk_destroy(self, request, *args, **kwargs):
         ],
     )
     def list(self, request, *args, **kwargs):
+        """List documents with optional filters. This is not to be confused with search.
+        This endpoint does not support full text search of the document collection.
+        For that, you are looking for
+        [documents_search_across](https://api.www.documentcloud.org/api/schema/redoc/#tag/documents/operation/documents_search_across).
+        If you are looking for text search within a single document to return text highlights, then
+        [documents_search_within_single_document](https://api.www.documentcloud.org/api/schema/redoc/#tag/documents/operation/documents_search_within_single_document)
+        is the correct endpoint. For performance reasons, this endpoint will not return a count of all objects,
+        only a link to next and previous.
+        """
         return super().list(request, *args, **kwargs)
 
     @extend_schema(
@@ -1116,7 +1125,11 @@ def _create_revision(self, document, old_processing, old_revision_control):
     @extend_schema(operation_id="documents_search_across")
     @action(detail=False, methods=["get"])
     def search(self, request):
-        """Search across all documents on DocumentCloud"""
+        """
+        Search across all documents on DocumentCloud with full text search using Solr.
+        Consult our [search documentation](https://www.documentcloud.org/help/search/) for a full parameter list.
+        This endpoint does return a full count, but does not provide a previous link.
+        """
         if settings.SOLR_DISABLE_ANON and request.user.is_anonymous:
             return Response(
                 {
@@ -1157,7 +1170,12 @@ def search(self, request):
     @extend_schema(operation_id="documents_search_within_single_document")
     @action(detail=True, url_path="search", methods=["get"])
     def page_search(self, request, pk=None):
-        """Search within a single document"""
+        """
+        Search within a single document using Solr.
+        This will return up to 25 text highlights
+        per response page for your query.
+        Consult our [search documentation](https://www.documentcloud.org/help/search/) for a full parameter list.
+        """
         if settings.SOLR_DISABLE_ANON and request.user.is_anonymous:
             return Response(
                 {

documentcloud/projects/views.py

@@ -96,7 +96,27 @@ def list(self, request, *args, **kwargs):
         return super().list(request, *args, **kwargs)
 
     @extend_schema(
-        request=ProjectSerializer,
+        request={
+            "application/json": {
+                "type": "object",
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "description": "Title of the project",
+                    },
+                    "description": {
+                        "type": "string",
+                        "maxLength": 1000,
+                        "description": "Optional description of the project",
+                    },
+                    "private": {
+                        "type": "boolean",
+                        "description": "Whether the project is private",
+                    },
+                },
+                "required": ["title"],
+            }
+        },
         responses={201: ProjectSerializer},
         examples=[
             OpenApiExample(