From f21877e9f835e63b8ba3265c466c157a6f44cf7b Mon Sep 17 00:00:00 2001
From: Jonathan Smith <20701-jonathan1055@users.noreply.drupalcode.org>
Date: Tue, 28 Jan 2025 10:19:43 +0000
Subject: [PATCH] Issue #3473000 by jonathan1055, fjgarlin: Documentation pages
---
assets/internal/.project-words.txt | 3 +++
docs/info/validation-jobs.md | 41 +++++++++++++++++++-----------
docs/jobs/pages.md | 36 +++++++++++++++++++++++++-
3 files changed, 64 insertions(+), 16 deletions(-)
diff --git a/assets/internal/.project-words.txt b/assets/internal/.project-words.txt
index 93eade75..fdb18de6 100644
--- a/assets/internal/.project-words.txt
+++ b/assets/internal/.project-words.txt
@@ -38,6 +38,9 @@ urls
readme
uncomment
testdox
+doctum
+phpdox
+documentor
# Invented words for the example of _cspell_words.
mycustomthing
madeupword
diff --git a/docs/info/validation-jobs.md b/docs/info/validation-jobs.md
index dc5df3dd..eb4ad1c9 100644
--- a/docs/info/validation-jobs.md
+++ b/docs/info/validation-jobs.md
@@ -1,46 +1,57 @@
# Validation jobs
-There are several code validation jobs, trying to mirror what core does.
-There is documentation for each of those jobs in:
+There are several code validation jobs, and these attempt to mirror what Drupal Core does. Separate documentation for each of these jobs is in:
+- [composer-lint](../jobs/composer-lint.md)
- [cspell](../jobs/cspell.md)
+- [eslint](../jobs/eslint.md)
+- [phpcs](../jobs/phpcs.md)
- [phpstan](../jobs/phpstan.md)
- [stylelint](../jobs/stylelint.md)
-- [eslint](./jobs/eslint.md)
-- [phpcs](../jobs/phpcs.md)
-- [composer-lint](../jobs/composer-lint.md)
## Allow failure in pipelines
-By default, all validation jobs are allowed to fail. This means that even if the job fails, the overall result of the pipeline will not be affected by it.
+By default, all validation jobs are allowed to fail. This means that even if a job reports failures, the overall result of the pipeline will not be affected by it. If there is a failure, the job will display an amber 'warning' instead of a red 'fail'.
-If the overall result of the pipeline is successful, and any of the validation jobs fail, then a warning icon will show.
+If a job is not allowed to fail then any reported problems will produce a red 'fail' and the overall pipeline status will be 'failed'.
There are several ways to alter this behavior, listed below.
### All validation jobs
-There is a special variable, named `_ALL_VALIDATE_ALLOW_FAILURE`, to control all the validation jobs `allow_failure`-behavior at once. Set to 1 to allow the all the validation/linting jobs to fail, set to 0 for not allowing any failure. Individual job variables can override this global settings.
+A variable named `_ALL_VALIDATE_ALLOW_FAILURE` can be used to control all the validation jobs `allow_failure`-behavior at once.
+
+Set this to 1 to allow the all the validation/linting jobs to fail, or set it to 0 for not allowing any failure. The default value is blank, which means that the pipeline jobs `allow_failure:` setting will be respected.
+
+Setting this variable in a pipeline UI form will override the setting committed in the project's `.gitlab-ci.yml` file.
```
variables:
_ALL_VALIDATE_ALLOW_FAILURE: 0
```
-### Per job
-There are individual variables to allow each job to fail (default value) or not. You just need to set these values to `0` in the `variables:` section in your `.gitlab-ci.yml` file, as shown below:
+### Overriding the 'all' setting per job
+There are individual variables to control the `allow_failure` setting for each job. These variables will take precedence over the `_ALL_VALIDATE_ALLOW_FAILURE` setting. Set to 1 to allow failure or 0 for not allowing failure. Leave blank or do not include the variable name to use the 'all' setting.
```
variables:
_COMPOSER_LINT_ALLOW_FAILURE: 0
- _PHPCS_ALLOW_FAILURE: 0
- _STYLELINT_ALLOW_FAILURE: 0
_CSPELL_ALLOW_FAILURE: 0
_ESLINT_ALLOW_FAILURE: 0
+ _PHPCS_ALLOW_FAILURE: 0
_PHPSTAN_ALLOW_FAILURE: 0
+ _STYLELINT_ALLOW_FAILURE: 0
```
-### Override the job value
-If you don't want to use any of the above variables, you can simply override the job value definition in your `.gitlab-ci.yml` file for the linting jobs where you want to change this behavior.
-
+### Override the job `allow_failure` value directly
+You can also override the job value definition in your `.gitlab-ci.yml` file for the linting jobs where you want to change this behavior from the Gitlab Templates default.
```
cspell:
allow_failure: false
```
+
+## Order of precedence
+The `allow_failure` setting for a particular job is determined by the following order - the first match in this list takes priority:
+1. The job-specific `_{name}_ALLOW_FAILURE` variable set in the UI pipeline form.
+1. The job-specific variable as defined in the `.gitlab-ci.yml` file
+1. `_ALL_VALIDATE_ALLOW_FAILURE` via the UI form
+1. `_ALL_VALIDATE_ALLOW_FAILURE` in the `.gitlab-ci.yml`
+1. The `allow_failure:` keyword setting for the job in `.gitlab-ci.yml`
+1. The `allow_failure:` keyword in the Gitlab Templates pipeline default.
diff --git a/docs/jobs/pages.md b/docs/jobs/pages.md
index 4f271517..02ee863a 100644
--- a/docs/jobs/pages.md
+++ b/docs/jobs/pages.md
@@ -1,5 +1,9 @@
# GitLab Pages
+The templates support the ability to publish a GitLab site. You can opt for using a supported default configuration or create your own integration.
+
+## Default configuration
+
Projects can automatically publish a documentation site powered by [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/).
- Get started by creating `mkdocs.yml` and `docs/index.md` files.
@@ -7,5 +11,35 @@ Projects can automatically publish a documentation site powered by [Material for
- With those in place, a site gets re-published every time the default branch changes. We only auto-publish the default branch for now.
- [Material for MkDocs has a great docs site](https://squidfunk.github.io/mkdocs-material/) and offers lots of plugins that should work on our GitLab pages. You may need to install their prerequisites in a `before_script` step in the pages job.
-## Project Logo
+### Project Logo
If the project has a logo image file `logo.png` this should be saved in the project's top-level directory, in accordance with the Drupal standard practice. However, the logo to be displayed in the MkDocs documentation site is taken from the `/docs` folder. This allows for an alternative logo on the documentation site. If there is no logo stored in the `/docs` folder then the file from the top-level folder will be used. You do not need to keep a duplicate file in both places.
+
+## Non-default configuration
+
+This option is also supported by [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/). All you need is to generate a `public` folder with the resulting static website that you want.
+
+The job definition can be like this:
+```
+pages:
+ stage: build
+ image: ubuntu <==== Any base image that you feel comfortable with
+ script:
+ - apt get ... <==== Install needed dependencies
+ - ./tool-of-choice . --output=public <==== Generate the site in the "public" folder.
+ - echo "The documentation will be published at $CI_PAGES_URL"
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+## PHPDocs Generators
+
+There are different tools that can generate a full documentation site based on your project's code comments. Some examples for PHP projects could be:
+
+- [Doctum](https://github.com/code-lts/doctum)
+- [Phpdox](https://phpdox.net/)
+- [PhpDocumentor](https://www.phpdoc.org/)
+
+You could automate those tools and make them generate a folder containing the documentation site and then connect it with the previous code.
--
GitLab