Formatting fixes

Are there any other formatting changes to make here? Anything for consistency across the sections?

Would you like this branch to temporarily build the actual documentation site, then we could check the built pages. I can add that here if it would be helpful.

Yes, it would be helpful. And I copied your work from the other issue and the pages are deployed for testing.

I went a bit all out on renaming files for simplicity and consistency.

There could be a few conflicts here, so I suggest we get MR2 and MR4 merged first, then see where we are.

I have aligned the pipeline changes with 'main' so we now run cspell and do not allow it to fail.

The pipeline failed but it seems that some of the spelling errors are in files that have been renamed. I updated the issue fork (using the gitlab UI when browing the repository) but that has not solved it.

@jonathan1055, apologies for the poor rebase I did. And thanks for the fixes.

No problem. I used the MR suggestions, to make it easier to see what was original and which new changes needed to be reverted.

Point 1 in PHP -> Quotes does not seem to be rendered properly. I have not done an exhaustive review of all the pages, but just mentioning things as I spot them. But it may be good to get these renames committed soon(ish) so that we don't get rebase errors again if new issue branches are opened.

This Data types section it not in sync with the d.o pages. This is one where I reverted the changed due to feedback in Slack and I didn't get back to properly review the situation. The discuss → tab for that page has more details. I'll make an effort to look into that today.

The compared the text on d.o with the issue ✨ Adopt phpstan phpdoc types as canonical reference of allowed types Active and it is mostly correct text. There is one sentence still there that should not be. I have made that change on d.o and to the MR.

I have added links to the documentation sites, as it can be confusing having two outputs here. This is only due to the temporary override in the .gitlab-ci.yml.

I'm going to see if we can find a better way to do this in Gitlab Templates generally, so that there is only one temporary documentation site, and the "live" site would only get updated on merging into the main repo.

Finally back here to finish this. There were eslint errors on the mkdocs.yml file, which don't make sense as that file is formatted correctly. And since there are no .js files here I have changed this to not run eslint.

If there are no objections then the only thing to do is to remove the temporary code in .gitlab-ci.yml and commit this.

I think the mkdocs file was clean before, but the new links had the wrong indentation. That can be fixed easily, then we can run the eslint job. I can do that here if you like, and also remove the temporary code.

Also the phpcs job (that currently runs) can be ignored, because Gitlab Templates has been corrected to better determine if php files can be checked. On the next release of the templates this job will not run.

All jobs are green, including eslint.

However, the changes to mkdocs.yml actually violate the current standard for YAML, which uses 2 spaces for indentation → not four. So, those should be reverted.

Yes, that page was written about config files but 2 spaces seems to be the norm in core.

I removed php/automated-tests.md based on 🌱 [META] [policy] Remove PHPUnit assertion messages when possible, and standardize remaining messages Active .

This is the list of remaining items from the original 'convert' issue.

1. Final check that the markdown files are up to date with what is on d.o
2. Update coding standard process to include docs MR in some step.
3. Update d.o. doc pages to redirect (or link) to new location.
4. Turn off editing of existing pages (or add a notice at top of each asking not to edit as the changes will be lost)
5. Create infrastructure issue for search and redirect. Similar to 📌 Automate publishing governance docs on drupal.org Active

Yes you are right that the yml standard for indentation is 2, and this is also enforced in the core .eslintrc.jon setting. For simple yml structures it is easy to see that two spaces are always used, but mkdocs.yml has a more complex nested structure. Here is an example which I did not change, it was alerady correct:

plugins:
  - search
  - privacy:
      enabled: !ENV [CI, false]

The "enabled" is indented 2 spaces from the start of "privacy" which actually menas 4 spaces from the '-' before the 'privacy'. But this looks fine and we did not complain. It looks at a passing glance that indentation of 2 is adhered to.

In a menu of nested links, the same principle applies:

nav:
  - Drupal Coding Standards:
      - Coding Standards: index.md

But in this case it looked wrong to you, because the new line also starts with '-'. The '- Coding' is indented 2 spaces from the start of the word 'Drupal' so it is actually 4 spaces from the '-' in front of Drupal. This may appear odd but it is what the eslint job is programmed to expect and report on. So I suggest we leave it as-is in the MR and we keep the eslint job running. The alternative is not to run eslint at all, but that would likely be worse as we'd potentially miss other violations of standards.

OK, fair enough.

I went to commit this but the diff stat doesn't match. GitLab shows 32 files + 725 − 664 and locally I get 34 files changed, 725 insertions(+), 804 deletions(-). I don't yet see why that is happening.

There are two files which were renamed but appear locally as a delete and new file, one affected 32 lines and the other 108. So together they account for the 2 extra files locally and the extra 140 deletions.

With this committed it seemed time to advertise that the docs are available via GitLab pages. So, I updated the top of the project page to indicate that.

These are still to do.

1. Final check that the markdown files are up to date with what is on d.o
2. Update coding standard process to include docs MR in some step.
3. Update d.o. doc pages to redirect (or link) to new location.
4. Turn off editing of existing pages (or add a notice at top of each asking not to edit as the changes will be lost)
5. Create infrastructure issue for search and redirect. Similar to 📌 Automate publishing governance docs on drupal.org Active

For
1. @jonathan1055 did a lot of review here so this should be fine. And anyone can open an issue to make corrections.
2. Should be an issue because this effects the issue template and the process.
3-5. Talk to infrastructure first, I think.

Leaving at NW to come back to make the follow ups.

Actually, on #27 point (1) I did not do any of that checking. I thought you did most of it, and maybe @borisson_ on 📌 Convert Coding Standards to GitLab pages Active but it wasn't me. I helped with the links, the gitlab-ci file and jobs, and the spelling and linting, but not any of the actual content of the pages.

automated-tests.md was removed but it's still in TOC

We need to lend support for ✨ Use markdown-link-check to verify .md links Active then this could have been picked automatically and fixed before merging.

MR6 is ready for review.
The site is built at

Actually the doc site has not been rebuilt because we don't have the temporary code in place to trigger the "pages" job. I want to make this more user-friendly for checking documentation fixes. See 📌 Only rebuild documentation pages when source has changed Active and 📌 Add documentation .md files to test the pages job Active .

Here is the updated site
https://coding-standards-3527545-5994d4.pages.drupalcode.org/

I've now removed the temporary code again. MR6 ready for review.

quietone → closed merge request !6

quietone → closed merge request !5

I created the issues needed from #27, 📌 Redirects for Coding standard pages to GitLab pages Active and 📌 Updates for using GitLab pages Active .

I think that completes this phase of the conversion. That just needs to be confirmed and then this can be set to 'fixed'.

For #27.1 I repeat that it was not me who did any content review. There may have been updates to some pages since the initial commits.

There was a discussion of the tasks and sequencing on 📌 Convert Coding Standards to GitLab pages Active so maybe it would be good to check against that, as the issue was closed before the tasks were marked off. It looks like most things have been covered though.

I have added a correction to my earlier comment about @jonathan1055 doing content review. @jonathan1055, is that change satisfactory?

Oh yes absolutely, and no apology is needed :-) I just didn't want people to think that all the content had been checked by me. I recall that you checked some 'last updated' dates previously and there was not much (if anything) that had been changed on the existing pages.

I have added your second follow-up issue to the summary.