2 files changed, 74 insertions, 0 deletions
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
index 131f43c..8fbcf2b 100644
--- a/docs/gl_objects/projects.py
+++ b/docs/gl_objects/projects.py
@@ -368,3 +368,29 @@ b_list.save()
 # board lists delete
 b_list.delete()
 # end board lists delete
+
+# project file upload by path
+# Or provide a full path to the uploaded file
+project.upload("filename.txt", filepath="/some/path/filename.txt")
+# end project file upload by path
+
+# project file upload with data
+# Upload a file using its filename and filedata
+project.upload("filename.txt", filedata="Raw data")
+# end project file upload with data
+
+# project file upload markdown
+uploaded_file = project.upload_file("filename.txt", filedata="data")
+issue = project.issues.get(issue_id)
+issue.notes.create({
+    "body": "See the attached file: {}".format(uploaded_file["markdown"])
+})
+# project file upload markdown
+
+# project file upload markdown custom
+uploaded_file = project.upload_file("filename.txt", filedata="data")
+issue = project.issues.get(issue_id)
+issue.notes.create({
+    "body": "See the [attached file]({})".format(uploaded_file["url"])
+})
+# project file upload markdown
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 4a8a0ad..b6cf311 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -779,3 +779,51 @@ Delete a list:
 .. literalinclude:: projects.py
    :start-after: # board lists delete
    :end-before: # end board lists delete
+
+
+File Uploads
+============
+
+Reference
+---------
+
+* v4 API:
+
+  + :attr:`gitlab.v4.objects.Project.upload`
+  + :class:`gitlab.v4.objects.ProjectUpload`
+
+* v3 API:
+
+  + :attr:`gitlab.v3.objects.Project.upload`
+  + :class:`gitlab.v3.objects.ProjectUpload`
+
+* Gitlab API: https://docs.gitlab.com/ce/api/projects.html#upload-a-file
+
+Examples
+--------
+
+Upload a file into a project using a filesystem path:
+
+.. literalinclude:: projects.py
+   :start-after: # project file upload by path
+   :end-before: # end project file upload by path
+
+Upload a file into a project without a filesystem path:
+
+.. literalinclude:: projects.py
+   :start-after: # project file upload with data
+   :end-before: # end project file upload with data
+
+Upload a file and comment on an issue using the uploaded file's
+markdown:
+
+.. literalinclude:: projects.py
+   :start-after: # project file upload markdown
+   :end-before: # end project file upload markdown
+
+Upload a file and comment on an issue while using custom
+markdown to reference the uploaded file:
+
+.. literalinclude:: projects.py
+   :start-after: # project file upload markdown custom
+   :end-before: # end project file upload markdown custom