docs: document CI Lint usage

nejch · JohnVillalovos · commit d5de4b1fe38b · 2022-07-05T09:19:34.000-07:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -13,6 +13,7 @@ API examples
    gl_objects/branches
    gl_objects/clusters
    gl_objects/messages
+   gl_objects/ci_lint
    gl_objects/commits
    gl_objects/deploy_keys
    gl_objects/deploy_tokens
diff --git a/docs/cli-examples.rst b/docs/cli-examples.rst
@@ -6,6 +6,48 @@ CLI examples
 
       For a complete list of objects and actions available, see :doc:`/cli-objects`.
 
+CI Lint
+-------
+
+Lint a CI YAML configuration from a string:
+
+.. note:: 
+
+   To see output, you will need to use the ``-v``/``--verbose`` flag.
+
+.. code-block:: console
+
+   $ gitlab --verbose ci-lint create --content \
+     "---
+     test:
+       script:
+         - echo hello
+     "
+
+Lint a CI YAML configuration from a file (see :ref:`cli_from_files`):
+
+.. code-block:: console
+
+   $ gitlab --verbose ci-lint create --content @.gitlab-ci.yml
+
+Lint a project's CI YAML configuration:
+
+.. code-block:: console
+
+   $ gitlab --verbose project-ci-lint create --project-id group/my-project --content @.gitlab-ci.yml
+
+Lint a project's current CI YAML configuration:
+
+.. code-block:: console
+
+   $ gitlab --verbose project-ci-lint get --project-id group/my-project
+
+Lint a project's current CI YAML configuration on a specific branch:
+
+.. code-block:: console
+
+   $ gitlab --verbose project-ci-lint get --project-id group/my-project --ref my-branch
+
 Projects
 --------
 
diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst
@@ -288,6 +288,8 @@ Example:
 
    $ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list
 
+.. _cli_from_files:
+
 Reading values from files
 -------------------------
 
diff --git a/docs/gl_objects/ci_lint.rst b/docs/gl_objects/ci_lint.rst
@@ -0,0 +1,53 @@
+#######
+CI Lint
+#######
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.CiLint`
+  + :class:`gitlab.v4.objects.CiLintManager`
+  + :attr:`gitlab.Gitlab.ci_lint`
+  + :class:`gitlab.v4.objects.ProjectCiLint`
+  + :class:`gitlab.v4.objects.ProjectCiLintManager`
+  + :attr:`gitlab.v4.objects.Project.ci_lint`
+
+* GitLab API: https://docs.gitlab.com/ee/api/lint.html
+
+Examples
+---------
+
+Validate a CI YAML configuration::
+
+    gitlab_ci_yml = """.api_test:
+      rules:
+        - if: $CI_PIPELINE_SOURCE=="merge_request_event"
+          changes:
+            - src/api/*
+    deploy:
+      extends:
+        - .api_test
+      rules:
+        - when: manual
+          allow_failure: true
+      script:
+        - echo "hello world"
+    """
+    lint_result = gl.ci_lint.create({"content": gitlab_ci_yml})
+
+    print(lint_result.status)  # Print the status of the CI YAML
+    print(lint_result.merged_yaml)  # Print the merged YAML file
+
+Validate a project's CI configuration::
+
+    lint_result = project.ci_lint.get()
+    assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
+    print(lint_result.merged_yaml)    # Print the merged YAML file
+
+Validate a CI YAML configuration with a namespace::
+
+    lint_result = project.ci_lint.create({"content": gitlab_ci_yml})
+    assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
+    print(lint_result.merged_yaml)    # Print the merged YAML file
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
@@ -819,49 +819,6 @@ Get total fetches in last 30 days of a project::
 
     total_fetches = project.additionalstatistics.get().fetches['total']
 
-Project CI Lint
-=============================
-
-Reference
----------
-
-* v4 API:
-
-  + :class:`gitlab.v4.objects.ProjectCiLint`
-  + :class:`gitlab.v4.objects.ProjectCiLintManager`
-  + :attr:`gitlab.v4.objects.Project.ci_lint`
-
-* GitLab API: https://docs.gitlab.com/ee/api/lint.html
-
-Examples
----------
-
-Validate a project's CI configuration::
-
-    lint_result = project.ci_lint.get()
-    assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
-    print(lint_result.merged_yaml)    # Print the merged YAML file
-
-Validate a CI YAML configuration with a namespace::
-
-    gitlab_ci_yml = """.api_test:
-      rules:
-        - if: $CI_PIPELINE_SOURCE=="merge_request_event"
-          changes:
-            - src/api/*
-    deploy:
-      extends:
-        - .api_test
-      rules:
-        - when: manual
-          allow_failure: true
-      script:
-        - echo "hello world"
-    """
-    lint_result = project.ci_lint.create({"content": gitlab_ci_yml})
-    assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
-    print(lint_result.merged_yaml)    # Print the merged YAML file
-
 Project storage
 =============================
 
