Merge pull request #1278 from creative-commoners/pulls/6.2/doclint

DOC Linting

Author: GuySartorelli

.doclintrc

@@ -0,0 +1 @@
+docs/en/

composer.json

@@ -41,6 +41,7 @@
     "require-dev": {
         "phpunit/phpunit": "^9.6",
         "squizlabs/php_codesniffer": "^3",
+        "silverstripe/documentation-lint": "^1",
         "silverstripe/standards": "^1",
         "phpstan/extension-installer": "^1.3"
     },
@@ -70,6 +71,11 @@
             "images"
         ]
     },
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
+    },
     "prefer-stable": true,
     "minimum-stability": "dev"
 }

docs/en/installation.md docs/en/01_installation.mddocs/en/installation.md renamed to docs/en/01_installation.md

@@ -1,16 +1,20 @@
+---
+title: Installation
+---
+
 # Installation
 
 Installation should be done using Composer:
 
-```
+```bash
 composer require silverstripe/userforms
 ```
 
 ## Configuration
 
 After installation, make sure you rebuild your database through `dev/build`.
 
-You should see a new page type in the CMS called 'User Defined Form'. This has a new 'Form' tab which has your form builder.
+You should see a new page type in the CMS called "User Defined Form". This has a new "Form" tab which has your form builder.
 
 ### File uploads and security
 
@@ -20,17 +24,17 @@ so they can be viewed later by CMS authors. Small files
 are also attached to the (optional) email notifications
 to any configured recipients.
 
-Allowed file extensions can be configured globally through `File.allowed_extensions`,
+Allowed file extensions can be configured globally through [`File.allowed_extensions`](api:SilverStripe\Assets\File->allowed_extensions),
 and default to a safe set of files (e.g. disallowing `*.php` uploads).
-You can define further exclusions through the `EditableFileField.allowed_extensions_blacklist`
+You can define further exclusions through the [`EditableFileField.allowed_extensions_blacklist`](api:SilverStripe\UserForms\Model\EditableFormField\EditableFileField->allowed_extensions_blacklist)
 configuration setting.
 
 The allowed upload size can be set in the CMS as long as it doesn't exceed the PHP configuration
 for this website (the smaller value of `upload_max_filesize` or `post_max_size`).
 
 ### Securing uploaded files
 
-By adding a File Upload Field to your user form you can allow your website users to upload files, which will be stored in a user-defined folder in your SilverStripe system. You can access these files via the "Submissions" tab, or from the "Files" area in the admin interface.
+By adding a File Upload Field to your user form you can allow your website users to upload files, which will be stored in a user-defined folder in your Silverstripe CMS system. You can access these files via the "Submissions" tab, or from the "Files" area in the admin interface.
 
 Please be aware that the responsibility of choosing a folder for files to be uploaded into is that of the CMS user. You can set the necessary "can view" permissions for the folder you create and/or choose via the "Files" section, then select that folder in the settings for the File Upload Field in your form.
 
@@ -44,18 +48,18 @@ In other cases, submissions could be expected to contain private data.
 
 If you want to use custom email templates set the following config option.
 
-```yaml
+```yml
 SilverStripe\UserForms\Model\UserDefinedForm:
   email_template_directory: mysite/templates/custom_userforms_emails/
 ```
 
-Any SilverStripe templates placed in your `email_template_directory` directory will be available for use with submission emails.
+Any templates placed in your `email_template_directory` directory will be available for use with submission emails.
 
 ### Custom multi-step button text
 
 If you want to change the button text when using the Multi-Step/Page Break feature, simply add the following to your `config.yml`:
 
-```yaml
+```yml
 SilverStripe\UserForms\Form\UserForm:
   button_text: 'Your Text Here'
 ```

docs/en/creating-custom-fields.md docs/en/02_creating-custom-fields.mddocs/en/creating-custom-fields.md renamed to docs/en/02_creating-custom-fields.md

@@ -1,10 +1,14 @@
+---
+title: Creating custom fields
+---
+
 # Creating custom fields
 
 To create and use your own custom fields, depending on what you want to accomplish, you may need to create two
 new classes subclassed from the following:
 
-- `EditableFormField` - this Field represents what will be seen/used in the CMS userforms interface
-- `FormField` - this Field represents what will be seen/used in the frontend user form when the above field has been
+- [`EditableFormField`](api:SilverStripe\UserForms\Model\EditableFormField) - this Field represents what will be seen/used in the CMS userforms interface
+- [`FormField`](api:SilverStripe\Forms\FormField) - this Field represents what will be seen/used in the frontend user form when the above field has been
 added
 
 ## How (without the "why")
@@ -13,9 +17,9 @@ You need to create your own subclass of `EditableFormField` (the field which wil
 implement the method `getFormField()`, which will need to return an instantiated `FormField` to be used in the
 frontend form.
 
-`EditableTextField` and `TextField` are two existing classes and probably the best example to look in to.
+[`EditableTextField`](api:SilverStripe\UserForms\Model\EditableFormField\EditableTextField) and [`TextField`](api:SilverStripe\Forms\TextField) are two existing classes and probably the best example to look in to.
 
-## Why two different Fields?
+## Why two different fields?
 
 Consider the following example (`EditableTextField` and `TextField`).
 

docs/en/troubleshooting.md docs/en/03_troubleshooting.mddocs/en/troubleshooting.md renamed to docs/en/03_troubleshooting.md

@@ -1,29 +1,34 @@
+---
+title: Troubleshooting
+---
+
 # Troubleshooting
 
 Check the below if you have any issues during installation or use
 
-## Installation Issues
+## Installation issues
 
 After installation make sure you have done a `dev/build` you may also need to flush the admin view by appending
-`?flush=1` to the URL, e.g. `http://yoursite.com/admin?flush=1`
+`?flush=1` to the URL, e.g. `https://example.com/admin?flush=1`
 
-## Checkbox or Radio group custom messages not showing
+## Checkbox or radio group custom messages not showing
 
 If your project has a custom template for `UserFormsCheckboxSetField.ss` or `UserFormsOptionSetField.ss`, then you will need to ensure they include `$Top.getValidationAttributesHTML().RAW`. See
-* [UserFormsCheckboxSetField.ss](../../templates/SilverStripe/UserForms/FormField/UserFormsCheckboxSetField.ss)
-* [UserFormsOptionSetField.ss](../../templates/SilverStripe/UserForms/FormField/UserFormsOptionSetField.ss)
 
-## UserForms EditableFormField Column Clean task
+- [UserFormsCheckboxSetField.ss](../../templates/SilverStripe/UserForms/FormField/UserFormsCheckboxSetField.ss)
+- [UserFormsOptionSetField.ss](../../templates/SilverStripe/UserForms/FormField/UserFormsOptionSetField.ss)
+
+## UserForms `EditableFormField` column clean task
 
-This task is used to clear unused columns from EditableFormField database tables.
+This [`UserFormsColumnCleanTask`](api:SilverStripe\UserForms\Task\UserFormsColumnCleanTask) task is used to clear unused columns from EditableFormField database tables.
 
 The reason to clear these columns is because having surplus forms can break form saving.
 
 Currently it only supports MySQL and when it is run it queries the EditableFormField class for the valid columns,
 it then grabs the columns for the live database. It will create a backup of the table and then remove any columns that
 are surplus.
 
-To run the task, log in as an administrator and go to to http://yoursite/dev/tasks/UserFormsColumnCleanTask in your browser, or run `sake dev/tasks/UserFormsColumnCleanTask` from the command line.
+To run the task, log in as an administrator and go to `https://example.com/dev/tasks/UserFormsColumnCleanTask` in your browser, or run `sake dev/tasks/UserFormsColumnCleanTask` from the command line.
 
 ## My CSV export times out or runs out of memory
 

docs/en/compiling-front-end-files.md

@@ -1,26 +1,21 @@
+---
+title: UserForms
+---
+
 # UserForms
 
 UserForms enables CMS users to create dynamic forms via a drag and drop interface
 and without getting involved in any PHP code.
 
 ## Features
 
-*  Construct a form using all major form fields (text, email, dropdown, radio, checkbox..)
-*  Ability to extend userforms from other modules to provide extra fields.
-*  Ability to email multiple people the form submission
-*  Custom email templates
-*  View submitted submissions and export them to CSV
-*  Define custom error messages and validation settings
-*  Optionally display and hide fields using javascript based on users input
-
-## Documentation
-
- * [Installation instructions](installation.md)
- * [Troubleshooting](troubleshooting.md)
- * [User Documentation](userguide/index.md)
- * [Compiling Front-End Files](compiling-front-end-files.md)
- * [Creating Custom Fields](creating-custom-fields.md)
- * [Upgrading to SilverStripe 4](upgrading.md)
+- Construct a form using all major form fields (text, email, dropdown, radio, checkbox..)
+- Ability to extend userforms from other modules to provide extra fields.
+- Ability to email multiple people the form submission
+- Custom email templates
+- View submitted submissions and export them to CSV
+- Define custom error messages and validation settings
+- Optionally display and hide fields using JavaScript based on users input
 
 ## Thanks
 
@@ -29,3 +24,5 @@ testers, clients who use the module and everyone that submits new features.
 
 A big thanks goes out to [Jan Düsedau](http://eformation.de) for drawing
 the custom icon set for the form fields.
+
+[CHILDREN includeFolders]

docs/en/index.md

@@ -18,10 +18,8 @@ drop-down menu will show up. Select "User Defined Form" Then hit the "Go" button
 
 You will notice that a new page has been created, with the name of "New User Defined Form." You will be taken to edit the page once you click "Create."
 
-<div class="note" markdown="1">
-Don't worry if you create your page in the "wrong" place. Pages can be moved and re-ordered
-easily.
-</div>
+> [!NOTE]
+> Don't worry if you create your page in the "wrong" place. Pages can be moved and re-ordered easily.
 
 ## Combining forms and content
 
@@ -31,10 +29,10 @@ however. You will notice in a newly created form page, there is some text in the
 of the editing menu to begin with: "$UserDefinedForm"
 
 The purpose of this little block of text is to tell the website where in the page you
-would like to put the form. The form will appear on the website wherever the "$UserDefinedForm"
+would like to put the form. The form will appear on the website wherever the `$UserDefinedForm`
 appears in the editing pane, whether it is before text, after text, inside a table, etc.
 
-If $UserDefinedForm is deleted by accident (or on purpose), SilverStripe automatically
+If $UserDefinedForm is deleted by accident (or on purpose), Silverstripe CMS automatically
 puts the form at the end of all the content.
 
 ![Form in content](_images/form-in-content.png)
@@ -67,3 +65,10 @@ Each message links to it's corresponding field so users can easily make the requ
 The 'Configuration' tab has a number of options used for customising your form's behaviour and appearance.
 
 ![Configuration](_images/userforms-config.png)
+
+## Creating a multi-page form
+
+To create a multi-page form, simply click the "Add Page Break" button.
+This will create a page break field which is used to create a new page in the form. You can drag and drop this page break to separate form fields at the desired location.
+
+![Multi-page forms](_images/multi-page-forms.png)