Issue #3473000 by jonathan1055, fjgarlin: Documentation pages

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

docs/info/validation-jobs.md

 # 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. 

docs/jobs/pages.md

 # 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.